Elliotte Harold schrieb:
> 
> 
> ROn 12/2/06, Bill de hOra <bill@dehora. net <mailto:bill%40dehora.net>> 
> wrote:
>  > >
>  > > It often seems to me that POST is a catchall for "do it". I guess the
>  > > reason I'm pushing on this is to figure out why the 2 verb web is a
>  > > runaway success. What's driving that? Is it because of the design
>  > > principles? Or because POST is so decoupled from meaning? Or would
>  > > things simply be much better even we had a broader vocabulary deployed
>  > > under the design principles?
> 
> I just did an interview with Bill Venners on exactly this:
> 
> http://www.artima. com/lejava/ articles/ why_put_and_ delete.html 
> <http://www.artima.com/lejava/articles/why_put_and_delete.html>

Commenting over here; I don't want to get an account over there just to 
add a comment...

Anyway: the issue of PUT and DELETE when being repeated potentially 
causing overlapping updates/deletes with somebody else's changes is 
solved in HTTP. Just send an "If-Match" request header with the last 
Etag you got from the server 
(<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.24>).

If you're lucky and the remote server knows how to deal with that 
properly, you can even avoid to re-send a large entity with PUT by using 
the "Expect: 100-continue" mechanism 
(<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.20>).

With respect to the original topic: can anybody point out why having 
*more* verbs would not be REST-ful? For instance, consider PATCH and 
COPY/MOVE...

Best regards, Julian

Hi Juilian,

On Jan 1, 2007, at 5:33 AM, Julian Reschke wrote:

> Elliotte Harold schrieb:
>>
>>
>> ROn 12/2/06, Bill de hOra <bill@dehora. net <mailto:bill% 
>> 40dehora.net>>
>> wrote:
>>>>
>>>> It often seems to me that POST is a catchall for "do it". I  
>>>> guess the
>>>> reason I'm pushing on this is to figure out why the 2 verb web is a
>>>> runaway success. What's driving that? Is it because of the design
>>>> principles? Or because POST is so decoupled from meaning? Or would
>>>> things simply be much better even we had a broader vocabulary  
>>>> deployed
>>>> under the design principles?
>>
>> I just did an interview with Bill Venners on exactly this:
>>
>> http://www.artima. com/lejava/ articles/ why_put_and_ delete.html
>> <http://www.artima.com/lejava/articles/why_put_and_delete.html>
>
> Commenting over here; I don't want to get an account over there  
> just to
> add a comment...
>
I don't like creating accounts everywhere either, but requiring  
accounts for forum postings at Artima allows me among other things to  
better deal with comment spam. I ask for a minimum amount of info.  
It's not much more onerous than subscribing to this mailing list was.

> Anyway: the issue of PUT and DELETE when being repeated potentially
> causing overlapping updates/deletes with somebody else's changes is
> solved in HTTP. Just send an "If-Match" request header with the last
> Etag you got from the server
> (<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.24>).
>
That's the missing bit of information I've been looking for. That's  
an optimistic locking approach, which should solve the problem I  
brought up of overlapping PUTs and DELETEs.

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

> If you're lucky and the remote server knows how to deal with that
> properly, you can even avoid to re-send a large entity with PUT by  
> using
> the "Expect: 100-continue" mechanism
> (<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.20>).
>
> With respect to the original topic: can anybody point out why having
> *more* verbs would not be REST-ful? For instance, consider PATCH and
> COPY/MOVE...
>
> Best regards, Julian
>
>
>
> Yahoo! Groups Links
>
>
>
>

> With respect to the original topic: can anybody point out why having
> *more* verbs would not be REST-ful? For instance, consider 
> PATCH and COPY/MOVE...

From the RTF Dissertation:
http://www.ics.uci.edu/~fielding/pubs/webarch_icse2000.pdf

=====
Connectors
REST uses various connector types to encapsulate the
activities of accessing resources and transferring resource
representations. The connectors present an abstract interface
for component communication, enhancing simplicity by
providing a clean separation of concerns and hiding the
underlying implementation of resources and communication
mechanisms. The generality of the interface also enables
substitutability: if the users' only access to the system is via
an abstract interface, the implementation can be replaced
without impacting the users. Since a connector manages
network communication for a component, information can
be shared across multiple interactions in order to improve
efficiency and responsiveness.
======

My view is that the 'generality of the interface' is decreased when
additional verbs are used. 
Another concern is that if there are several different approaches for any
given task, an application has to deal with each of the approaches and this
can be costly. If a particular verb could be re-phrased in terms of other
verbs, then those other verbs are more 'primitive'. With only a few
'primitive' ways of doing many things there is less need to adapt to many
different approaches - a cheaper way to conduct business.
For example, it's hard to argue that DELETE could be rephrased as GET and
vice-versa. It's easier to argue that PATCH could be rephrased as a PUT or
POST to a related 'metadata' resource. 
In addition, with too few operations there is less visibility on the meaning
and purpose of an operation which could result in a loss of efficiency or
other undesired characteristics. For example, using POST to delete
representations rather than DELETE may work, but you lose the predictable
repeatability of DELETE (you can resubmit a DELETE in the face of network
issues, but it's a bad idea to resubmit a POST unless you have
custom/external information indicating that it's okay - in which case, it's
just like a DELETE only misspelled).

On Jan 1, 2007, at 12:22 PM, S. Mike Dierken wrote:

> > With respect to the original topic: can anybody point out why having
> > *more* verbs would not be REST-ful? For instance, consider
> > PATCH and COPY/MOVE...
>
> >From the RTF Dissertation:
> http://www.ics.uci.edu/~fielding/pubs/webarch_icse2000.pdf
>
> =====
> Connectors
> REST uses various connector types to encapsulate the
> activities of accessing resources and transferring resource
> representations. The connectors present an abstract interface
> for component communication, enhancing simplicity by
> providing a clean separation of concerns and hiding the
> underlying implementation of resources and communication
> mechanisms. The generality of the interface also enables
> substitutability: if the users' only access to the system is via
> an abstract interface, the implementation can be replaced
> without impacting the users. Since a connector manages
> network communication for a component, information can
> be shared across multiple interactions in order to improve
> efficiency and responsiveness.
> ======
>
> My view is that the 'generality of the interface' is decreased when
> additional verbs are used.

I disagree.  The generality refers to all resources having the same
interface, not all resources having an artificially limited interface.
It isn't even necessary for all resources to support the same set of
methods -- only that, when supported, they mean the same thing to all
resources.

PATCH was in my original HTTP/1.1 proposal and, assuming it is
implemented the way I described, is just as RESTful as PUT.

The limiting factor of only a few methods is a side-effect of the
architectural constraint.  Given that all methods have to mean the
same thing to all resources, there are a very limited number of
semantics that can usefully fit within a method.

> Another concern is that if there are several different approaches  
> for any
> given task, an application has to deal with each of the approaches  
> and this
> can be costly. If a particular verb could be re-phrased in terms of  
> other
> verbs, then those other verbs are more 'primitive'. With only a few
> 'primitive' ways of doing many things there is less need to adapt  
> to many
> different approaches - a cheaper way to conduct business.
> For example, it's hard to argue that DELETE could be rephrased as  
> GET and
> vice-versa. It's easier to argue that PATCH could be rephrased as a  
> PUT or
> POST to a related 'metadata' resource.

So can DELETE.  PATCH has very specific semantics and a very specific
goal of reducing bits on updates.  It is a separate method because it
needs access to the same (generic) conditional mechanisms as PUT and
because POST (when applied to an authorable resource) means append.

MOVE and COPY are namespace operations.  The problem with the
WebDAV definitions are that they target the wrong resource and then
stick another URI in an arbitrary header field.  That is due to trying
to squeeze a multitarget operation into a protocol (HTTP) that simply
wasn't designed for multiple targets.  The target should be the
collection that is being changed.  This is an architecture detail,
not a question of architectural style.

REPORT, on the other hand, is just plain evil.  It is bad architecture,
violates REST, avoids giving a URI to important resources, and tunnels
arbitrary methods through HTTP.

....Roy

On Mon, 2007-01-01 at 14:33 +0100, Julian Reschke wrote:
> With respect to the original topic: can anybody point out why having 
> *more* verbs would not be REST-ful? For instance, consider PATCH and 
> COPY/MOVE...

REST does not constrain the available methods to GET, PUT, POST, DELETE.
It does, however, constrain the available methods to be some
universally-understood set. In REST this set is meant to evolve over
time as new demands are placed on the architecture, just as new content
types are added as new demands emerge. New methods are supposed to be
added over time. Unused methods eventually should be deprecated. The
fact that we have gotten away with so few methods for so long on the web
suggests that the web is a fairly mature architecture. It is probably
also influenced by the amount of tunnelling (or at least "process this")
that tends to go over the POST method.

Benjamin

Roy T. Fielding schrieb:
> ...
> REPORT, on the other hand, is just plain evil.  It is bad architecture,
> violates REST, avoids giving a URI to important resources, and tunnels
> arbitrary methods through HTTP.
> ...

Sorry?

REPORT be definition isn't as bad as POST, being a safe method. Thus, it 
can *not* tunnel arbitrary methods, at least as long as the people using 
it read the method definition 
(<http://greenbytes.de/tech/webdav/rfc3253.html#rfc.section.3.6>).

Best regards, Julian

S. Mike Dierken wrote:

> For example, it's hard to argue that DELETE could be rephrased as GET and
> vice-versa. It's easier to argue that PATCH could be rephrased as a PUT or
> POST to a related 'metadata' resource. 

I suspect PATCH is most effectively rephrased as it is now: a PUT of the 
entire resource rather than a diff file. For most use cases there just 
isn't enough benefit to sending only the diffs to justify a new verb. 
That's more true as time passes and bandwidth expands. Plus it handily 
avoids the question of defining the diff format and patch algorithm.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

> > For example, it's hard to argue that DELETE could be rephrased as GET 
> > and vice-versa. It's easier to argue that PATCH could be rephrased as 
> > a PUT or POST to a related 'metadata' resource.
> 
> So can DELETE.  PATCH has very specific semantics and a very 
> specific goal of reducing bits on updates.  It is a separate 
> method because it needs access to the same (generic) 
> conditional mechanisms as PUT and because POST (when applied 
> to an authorable resource) means append.
Sorry - I used PATCH in that example without knowing the actual semantics. I
think I had it confused with PROPPATCH. Or I was simply confused.
I've been looking for a 'partial update' operation, so I'll take a look at
PATCH - is this the authoritative description:
http://www.w3.org/Protocols/HTTP/1.1/spec.html#PATCH

Elliotte Harold wrote:
> 
> 
> Paul Downey wrote:
>
>  > 3) as essential as PUT and DELETE are, they're blocked by many
>  > firewall/proxies and it's a brave API developer who
>  > depends upon them ..
> 
> Yes, that's a problem, though I really don't think that tunneling PUT
> and DELETE through GET and POST is the solution. I tend to believe that
> firewall preferences should be respected. If someone has chosen to block
> the functionality of PUT and DELETE, then that's there decision and we
> should respect it.

PUT maybe I can live without; tunneling DELETE over POST is nauseating.

But this thing about firewalls is a tad backways. Firewall admins don't 
really want to block PUT and DELETE (that's the DBA's job). I think the 
admins also learned from subsetted examples.

cheers
Bill

Elliotte Harold wrote:

> Is there anyway to ask a server whether it considers two URLs to be the
> same? Should there be?

Not in HTTP. But you can express "Hesperus is Phosphorus" class 
equivalence with OWL using sameAs and you can expose a query service 
that can answer yes or no for sameAs using SPARQL.

cheers
Bill

Elliotte Harold wrote:
> 
> 
> Nic James Ferrier wrote:
> 
>  > I think we probably shouldn't respect it because it's probably not
>  > been done for the right reasons.
> 
> And you know that how? It is not your place to say that I have
> configured my firewall improperly. 

'Cos if you had your firewall configured properly, you'd block POST first.

cheers
Bill

Mike Schinkel wrote:
> > Ah yes, the ugly '@' prefix. It's to avoid naming clashes between
> > built-in and custom URIs. 
> 
> I definitely wouldn't use something that requires encoding.

It doesn't.  According to [1] (section 3.3), the '@' character is
legal in the URI path and does not require escaping.


Cheers,

- Steve

[1] http://www.ietf.org/rfc/rfc2396.txt

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Hugh Winkler wrote:
> >
> > In other words, I can see how the form can be generated from the
> > schema (modulo input field descriptions), but I'm not sure how to
> > infer the complete schema from a form.  Are there examples of this?
> >
> 
> Unsure I'm understanding you: Why would you want to infer a complete
> schema from a form?

To do input validation.  Let me explain: I'm currently pondering how
to best deal with resources that are pure behaviors (i.e. only accept
POST) in Dream, our REST framework.  If I associate a RelaxNG schema
with the resource, I can use it to validate input before it reaches
the implementation; and I _could_ use it to generate a form.  The form
would be returned on a GET request, making the resource reflective (or
self-descriptive).  Now, developers could use the form to interact
with the resource directly, which has a lot pedagogical value.

However, if I take the opposite approach, meaning that if a GET were
to return a form, I would not get the automatic input validation
benefit unless I were able to generate the schema from the form.

Thus, my current inclination is to use a RelaxNG schema to both do
input validation and interact with the resource.


- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

I've created a short tutorial on REST and some common resource/service
patterns.  The tutorial is based on my experience with designing the
API for our DekiWiki application [1].

I would welcome feedback on the accuracy of the content.  The tutorial
will be used to introduce developers to REST and establish a common
framework for designing services.
http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us

Thanks in advance for taking a look at it.


Cheers,

- Steve

[1] http://doc.opengarden.org/DekiWiki_API/Reference/DekiWiki

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Steve G. Bjorg wrote: 
> Mike Schinkel wrote:
> > > Ah yes, the ugly '@' prefix. It's to avoid naming clashes between
> > > built-in and custom URIs. 
> > 
> > I definitely wouldn't use something that requires encoding.
> 
> It doesn't. According to [1] (section 3.3), the '@' character is
> legal in the URI path and does not require escaping.
> [1] http://www.ietf.org/rfc/rfc2396.txt 

I didn't check rfc 2396, but rfc 3986 obsoletes it.  Reading from "Reserved
Characters" section[1] it appears that you should percent encode the '@'
character, but I could be misreading.  Can anyone on the list with more
experience tell me if I'm interpreting it incorrectly, and if so why?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

I've been reflecting a little on this issue with versioned resources and
the fact that a straightforward PUT would not be idempotent (or at least
not exactly), but a PUT-302-PUT combination involves sending the content
payload twice (a nasty shock for the author wanting to upload her 1GB
video file).

Is it possible to use the Expect mechanism to avoid having to send the
payload for the first PUT? If so, what would the dialogue look like,
would it involve a 302 or a 417 response, and can you even have a
Location header with a 417 response?
-- 
Chris Burdess

Chris Burdess schrieb:
> 
> 
> I've been reflecting a little on this issue with versioned resources and
> the fact that a straightforward PUT would not be idempotent (or at least
> not exactly), but a PUT-302-PUT combination involves sending the content
> payload twice (a nasty shock for the author wanting to upload her 1GB
> video file).

When using DeltaV (RFC3744), a PUT will always be idempotent unless you 
enable auto-versioning.

> Is it possible to use the Expect mechanism to avoid having to send the
> payload for the first PUT? If so, what would the dialogue look like,
> would it involve a 302 or a 417 response, and can you even have a
> Location header with a 417 response?

I would think so. The server would immediately send the 302 with the 
Location header.

One related problem is that the Java servlet API doesn't really allow 
servlet based servers to do the right thing here. It would be really 
nice if there'd be some progress on that. 
(<http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4812000>).

Best regards, Julian

On Tue, 2007-01-02 at 11:57 +0000, Chris Burdess wrote:
> I've been reflecting a little on this issue with versioned resources
> and
> the fact that a straightforward PUT would not be idempotent (or at
> least
> not exactly), but a PUT-302-PUT combination involves sending the
> content
> payload twice (a nasty shock for the author wanting to upload her 1GB
> video file).

I'm not familiar with with the original discussion, but why should a 302
be necessary?

If I PUT several times to <http://example.com/mydocument>, is it
important to me that the <http://example.com/mydocument;1>,
<http://example.com/mydocument;2>, and <http://example.com/mydocument;3>
resources are created? My operation has succeeded. Whatever else the
server chooses to do with my submission is up to it. I don't see any
need to redirect a client to a specific new document version in order to
allow their PUT operation to proceed.

Benjamin.

On Tue, 2007-01-02 at 06:57 -0500, Mike Schinkel wrote:
> Steve G. Bjorg wrote: 
> > Mike Schinkel wrote:
> > > > Ah yes, the ugly '@' prefix. It's to avoid naming clashes
> between
> > > > built-in and custom URIs. 
> > > I definitely wouldn't use something that requires encoding.
> > It doesn't. According to [1] (section 3.3), the '@' character is
> > legal in the URI path and does not require escaping.
> > [1] http://www.ietf.org/rfc/rfc2396.txt 
> I didn't check rfc 2396, but rfc 3986 obsoletes it. Reading from
> "Reserved
> Characters" section[1] it appears that you should percent encode the
> '@'
> character, but I could be misreading. Can anyone on the list with more
> experience tell me if I'm interpreting it incorrectly, and if so why?

"@" is legal in most parts of a uri, since it is part of the pchar set.

As for the RESTfulness or not of dream, I suppose I have some comments.
I am reading
<http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us>.

My initial reactions:
* In REST it is likely that multiple resources will be served from a
single defined set of state, ie a service. For example an object or a
set of objects are likely to have several resources associated with them
that act as the network interface to these objects. I would suggest that
instead of "Each Dream service (being) a resource", each dream service
should make a set of resources available. 
* Returning a dream blueprint to users of the system doesn't read to me
as useful. If the blueprint exposure is an internal deployment
mechanism, this is ok. The blueprint appears to be an internal document
that allows particular methods on particular resources to be mapped to
other method invocations on internally-defined objects. This is fine,
but should not normally be communicated to users of the interface. Users
should see published lists of URIs that meet particular requirements the
uses may have. Perhaps a cut-down form of the blueprint would be more
appropriate than one that exposes internal classes and the like.
* It looks like access to HTML headers and the like may be limited.
Where is the url returned in a POST's Location header in
<http://doc.opengarden.org/Dream_SDK/Tutorials/Address_Book>?

On the whole the framework doesn't look particularly RESTful or
non-RESTful. It would be up to a particular blueprint and implementation
to conform or not conform to REST principles. If it is designed for
interaction with HTTP and allows appropriate access to HTTP headers I
don't see any obvious problems on the surface.

Benjamin

On Jan 2, 2007, at 3:19 PM, Benjamin Carlyle wrote:

> On Tue, 2007-01-02 at 11:57 +0000, Chris Burdess wrote:
>> I've been reflecting a little on this issue with versioned resources
>> and
>> the fact that a straightforward PUT would not be idempotent (or at
>> least
>> not exactly), but a PUT-302-PUT combination involves sending the
>> content
>> payload twice (a nasty shock for the author wanting to upload her 1GB
>> video file).
>
> I'm not familiar with with the original discussion, but why should  
> a 302
> be necessary?

Because the resource the client intended to update remains unapdated,
thus the expectation implied by PUT fails and therfore a 2xx is  
inappropriate.
>
> If I PUT several times to <http://example.com/mydocument>, is it
> important to me that the <http://example.com/mydocument;1>,
> <http://example.com/mydocument;2>, and <http://example.com/ 
> mydocument;3>
> resources are created? My operation has succeeded.

No, because http://example.com/mydocument is not being changed.

Jan


> Whatever else the
> server chooses to do with my submission is up to it. I don't see any
> need to redirect a client to a specific new document version in  
> order to
> allow their PUT operation to proceed.


>
> Benjamin.
>
>
>
>
>
> Yahoo! Groups Links
>
>
>

Jan Algermissen schrieb:
> 
> 
> 
> On Jan 2, 2007, at 3:19 PM, Benjamin Carlyle wrote:
> 
>  > On Tue, 2007-01-02 at 11:57 +0000, Chris Burdess wrote:
>  >> I've been reflecting a little on this issue with versioned resources
>  >> and
>  >> the fact that a straightforward PUT would not be idempotent (or at
>  >> least
>  >> not exactly), but a PUT-302-PUT combination involves sending the
>  >> content
>  >> payload twice (a nasty shock for the author wanting to upload her 1GB
>  >> video file).
>  >
>  > I'm not familiar with with the original discussion, but why should
>  > a 302
>  > be necessary?
> 
> Because the resource the client intended to update remains unapdated,
> thus the expectation implied by PUT fails and therfore a 2xx is
> inappropriate.
>  >
>  > If I PUT several times to <http://example. com/mydocument 
> <http://example.com/mydocument>>, is it
>  > important to me that the <http://example. com/mydocument; 1 
> <http://example.com/mydocument;1>>,
>  > <http://example. com/mydocument; 2 
> <http://example.com/mydocument;2>>, and <http://example. com/ 
> <http://example.com/>
>  > mydocument;3>
>  > resources are created? My operation has succeeded.
> 
> No, because http://example. com/mydocument 
> <http://example.com/mydocument> is not being changed.

Well, all the problems go away if the resource *is* changed.

I have the feeling of "not-invented-here". Can anybody please explain 
why it's so bad to just do what RFC3744 describes as "checkout-in-place" 
feature?

Best regards, Julian

On 1/2/07, Julian Reschke <julian.reschke@...> wrote:
> [snip] Can anybody please explain
> why it's so bad to just do what RFC3744 describes as "checkout-in-place"
> feature?

Because it violates idempotency, see
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.2

'Silently' creating a new copy (on a public URI) as you suggest has a
side-effect (namely an increment of the publicly-visible version
number).

However, if the request returns a redirect to the next version number
then the caller can elect not to follow the redirect if they choose
(or PUT repeatedly and idempotently onto the 'versioned' URI)

Of course, if the versioning is entirely private and not accessible to
callers, you can do whatever you like. Idempotency only refers to what
callers can see evidence of.

Hope that helps,
Alan Dean

On Jan 2, 2007, at 4:00 PM, Julian Reschke wrote:

>
>
> Well, all the problems go away if the resource *is* changed.

The issue IMO is that the client needs no knowledge whatsoever about  
versioning, it just understands PUT and the server uses plain HTTP  
facilities (redirect) to guide the client. The client will work  
equally with a non-versioning and a versioning server. In fact, the  
client hardly cares if there are versions or not, it just wants the  
server to 'store' what it sends.

Jan

>
> I have the feeling of "not-invented-here". Can anybody please  
> explain why it's so bad to just do what RFC3744 describes as  
> "checkout-in-place" feature?
>
> Best regards, Julian
>
>

Jan Algermissen schrieb:
> 
> 
> 
> On Jan 2, 2007, at 4:00 PM, Julian Reschke wrote:
> 
>  >
>  >
>  > Well, all the problems go away if the resource *is* changed.
> 
> The issue IMO is that the client needs no knowledge whatsoever about
> versioning, it just understands PUT and the server uses plain HTTP
> facilities (redirect) to guide the client. The client will work
> equally with a non-versioning and a versioning server. In fact, the
> client hardly cares if there are versions or not, it just wants the
> server to 'store' what it sends.
> 
> Jan

Can you please explain how that would work with existing clients that 
follow HTTP/1.1 with respect to not following redirects for unsafe 
methods? (pointer?)

Best regards, Julian

Benjamin Carlyle wrote:
> > I've been reflecting a little on this issue with versioned resources
> > and
> > the fact that a straightforward PUT would not be idempotent (or at
> > least
> > not exactly), but a PUT-302-PUT combination involves sending the
> > content
> > payload twice (a nasty shock for the author wanting to upload her 1GB
> > video file).
> 
> I'm not familiar with with the original discussion, but why should a 302
> be necessary?

See the thread

  http://tech.groups.yahoo.com/group/rest-discuss/message/7254

> If I PUT several times to <http://example.com/mydocument>, is it
> important to me that the <http://example.com/mydocument;1>,
> <http://example.com/mydocument;2>, and <http://example.com/mydocument;3>
> resources are created? My operation has succeeded. Whatever else the
> server chooses to do with my submission is up to it. I don't see any
> need to redirect a client to a specific new document version in order to
> allow their PUT operation to proceed.

It does seem to be a bit of a bone of contention. If we assume that
/mydocument *does* change, i.e. that it is equivalent to
/mydocument;current or maybe /mydocument?revision=current , and always
reflects the state of the last change, then the PUT to /mydocument is
only idempotent with respect to /mydocument and not to the entire
namespace. This is a problem since RFC 2616 defines an idempotent method
in terms of its side-effects not its direct effects, if you see what I
mean.
-- 
Chris Burdess

On Jan 2, 2007, at 4:15 PM, Chris Burdess wrote:

> If we assume that
> /mydocument *does* change, i.e. that it is equivalent to
> /mydocument;current or maybe /mydocument?revision=current , and always
> reflects the state of the last change

The problem with this is that it only works with linear versioning;  
branching is not possible.

Jan 

[ Attachment content not displayed ]

On Jan 2, 2007, at 4:46 PM, Julian Reschke wrote:

>
> Can you please explain how that would work with existing clients that
> follow HTTP/1.1 with respect to not following redirects for unsafe
> methods? (pointer?)

Are you refering to section 10.3? I am not sure how much this  
constraint is targeted towards software user agents (as it  
specificaly mentiones the user). IMHO, it is a configuration issue -  
if the user instructs the user agent to follow the redirects by  
default, that would not contradict the specs (IMHO).

I read it to mean that the user agent implementation should nt  
silently follow the redirect but provide a means to detect it (if  
desired).

Could be wrong though - is it?

Jan




>
> Best regards, Julian
>
>
>
>
> Yahoo! Groups Links
>
>
>

Jan Algermissen schrieb:
> 
> On Jan 2, 2007, at 4:00 PM, Julian Reschke wrote:
> 
>>
>>
>> Well, all the problems go away if the resource *is* changed.
> 
> The issue IMO is that the client needs no knowledge whatsoever about 
> versioning, it just understands PUT and the server uses plain HTTP 
> facilities (redirect) to guide the client. The client will work equally 
> with a non-versioning and a versioning server. In fact, the client 
> hardly cares if there are versions or not, it just wants the server to 
> 'store' what it sends.

Well, I personally think that a redirect here is the wrong approach. If 
only if user agents only may follow a redirect without user interaction 
if the method is safe, which PUT is not (see 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.10.3>).

Best regards, Julian

Benjamin Carlyle wrote:
> "@" is legal in most parts of a uri, since it is part of the 
> pchar set.

Thanks. Reading those specs correctly is so tricky...

> Perhaps a cut-down 
> form of the blueprint would be more appropriate than one that 
> exposes internal classes and the like.

That's what I was enivisoning since they are so closely related.

> On the whole the framework doesn't look particularly RESTful 
> or non-RESTful. It would be up to a particular blueprint and 
> implementation to conform or not conform to REST principles. 
> If it is designed for interaction with HTTP and allows 
> appropriate access to HTTP headers I don't see any obvious 
> problems on the surface.

I'm curious; could RESTfulness be more strongly enforced by the framework?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Alan Dean schrieb:
> 
> 
> On 1/2/07, Julian Reschke <julian.reschke@ gmx.de 
> <mailto:julian.reschke%40gmx.de>> wrote:
>  > [snip] Can anybody please explain
>  > why it's so bad to just do what RFC3744 describes as "checkout-in- place"
>  > feature?
> 
> Because it violates idempotency, see
> http://www.w3. org/Protocols/ rfc2616/rfc2616- sec9.html# sec9.1.2 
> <http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.2>
> 
> 'Silently' creating a new copy (on a public URI) as you suggest has a
> side-effect (namely an increment of the publicly-visible version
> number).

But that is only the case when you have a server with autoversioning. 
PUT on a RFC3744-versioncontrolled resource is idempotent unless you do 
autoversioning.

> However, if the request returns a redirect to the next version number
> then the caller can elect not to follow the redirect if they choose
> (or PUT repeatedly and idempotently onto the 'versioned' URI)

If a PUT request returns a 3xx, a sane client will assume that the PUT 
has not been executed at all.

> Of course, if the versioning is entirely private and not accessible to
> callers, you can do whatever you like. Idempotency only refers to what
> callers can see evidence of.
> 
> Hope that helps,
> Alan Dean

Best regards, Julian

Stelios Eliakis write:
>> I don't know how to handle opaque URIs 
>> in Apache. I want /myserver/products/1/ 
>> to run an index.php and /myserver/products/ 
>> to run the same index.php etc. Do you know 
>> how can I do it without copy this file in every 
>> directory? 

Can't you just use mod_rewrite for that?
(Are you familiar with using mod_rewrite?)

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Walden Mathews wrote:
> Maintaining multiple URIs for the same resource is not
> best practice. For the same reason you want uniformity in
> methods, you want one preferred URI for identifying a
> resource. The server should redirect requests for other
> equivalent URIs to the preferred one. Althought that's not
> quite what you are asking, I think it is the answer.

I'm curious why you make the above statement. Is there a W3C finding that documents this, or some other paper?  I've been doing a significant amount of research on URLs and URI best practices in the past 3+ months and have found nothing like this (though I could have missed it.) 

To me, is appears on the surface to be a sound engineering principle, but in practice an unreasonable constraint.  Given my research I've come to the conclusion there is a need for additional metadata standards that would allow better determination of URL equivalence when the expense of retrieving the resource is not prohibitive.

=============
Consider a blog with the following URL structure:

	http://www.myblog.com/{author}/{year}/{month}/{day}/{post-name}/

Not let's assume those are hackable URLs, which mean that all of the following will provide appropriate lists of posts with each one having a breadcrumb path at the top:

	http://www.myblog.com/{author}/{year}/{month}/{day}/
		Home > {author} > {year} > {month} 

	http://www.myblog.com/{author}/{year}/{month}/
		Home > {author} > {year} 

	http://www.myblog.com/{author}/{year}/
		Home > {author} 

	http://www.myblog.com/{author}/
		Home 

Now given that, I might also want to have the following, each with it's own appropriate breadcrumbs

	http://www.myblog.com/{year}/
		Home 

	http://www.myblog.com/{year}/{month}/
		Home > {year} 

	http://www.myblog.com/{year}/{month}/{author}/
		Home > {year} > {month}

	http://www.myblog.com/{year}/{author}/{post-name}/
		Home > {year} > {month} > {author}

(We are ignoring the problem of duplicates on a day or for an author within a year. I have strategies for handling but would make my reply much longer and isn't important for this discussion of this issue.)

So a user decides to drill down the year/month/author path and then selects a post. They read the post and then look to click the breadcrumb to go back to author's page.

But wait, the year/month/author breadcrumb isn't there because the server redirected them to the author/year/month version of the URL.  The user is rather confused, and frankly a but pissed off because they had seen an article they wanted to read but were not sure where it was now. So they leave the website in a huff vowing never to return.

=============

Consider another set of URLS:

	http://www.mycarsite.com/{make}/{model}/{year}/

But it's also logical to have:

	http://www.mycarsite.com/{year}/{make}/{model}/

Or even:

	http://www.mycarsite.com/{make}/{year}/{model}/

=============

And those are but two examples, I have (literally) tens if not hundreds more examples I could provide.  I can't imagine it would be good human interface to bounce users around like you are suggesting.

Basically we are talking about information that can be viewed as a heirarchy but for which the heirarchy is mutable. Essentially we are talking about Matrix URIs [1] where the only difference is slashes instead of semi-colons (the semi-colon syntax never caught on and at this point I would guess both web developers and users are more comfortable understanding slashes in their URLs compared with semi-colons.)

So wouldn't Matrix URIs violate the principles you mention above?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://www.w3.org/DesignIssues/MatrixURIs.html
So it seems to me there is a 



	
	Walden
	
	----- Original Message ----- 
	From: "Elliotte Harold" <elharo@... <mailto:elharo%40metalab.unc.edu> >
	To: "REST Discuss" <rest-discuss@yahoogroups.com <mailto:rest-discuss%40yahoogroups.com> >
	Sent: Sunday, December 31, 2006 8:24 AM
	Subject: [rest-discuss] Determining the equality of two URLs
	
	: How would one determine the deep equality of two URLs? That is, it is
	: possible for two URLs to identify the same resource, but how can one
	: know this? (aside from trivial cases like http://www.oreilly.com <http://www.oreilly.com>  and
	: http://www.oreilly.com:80/ <http://www.oreilly.com:80/>  )
	:
	: Is there anyway to ask a server whether it considers two URLs to be the
	: same? Should there be?
	:
	: You could certainly implement this as a GET to a special URL on the
	: server, but I'm beginning to wonder if this is a special case like HEAD
	: where an additional verb might actually make sense.
	:
	: -- 
	: Elliotte Rusty Harold elharo@... <mailto:elharo%40metalab.unc.edu> 
	: Java I/O 2nd Edition Just Published!
	: http://www.cafeaulait.org/books/javaio2/ <http://www.cafeaulait.org/books/javaio2/> 
	: http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/ <http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/> 
	:
	:
	: __________ NOD32 1949 (20061230) Information __________
	:
	: This message was checked by NOD32 antivirus system.
	: http://www.eset.com <http://www.eset.com> 
	:
	: 
	
	

	 

Elliotte Harold wrote:
>Nic James Ferrier wrote:
>
>>What reason can there be for preventing ones users from sending PUT or
>>DELETE?
>>
>>I can't see one.
>>
>
>Irrelevant. If the firewall admins see one, that's good enough. It's 
>their firewall, not yours. If the internal users are inconvenienced then 
>they are free to lobby to change their organization's firewall policy, 
>through whatever means are available within their organization. 

No, that's not reality. 

The internal admins configuring the firewall in many places are clueless
(believe me, I ran a business for a while where that was truly the case but
I couldn't afford to hire anyone better. And it will be the case in many
small to medium size businesses.)

The users will not know that the website is respecting their firewall "as it
should", all they will know is that the service doesn't work for them and
they won't have a clue that it has anything to do with the firewall (even if
the website tells them.) All they will know is they they are going to give
their business to that other website that does what it needs to do in order
to work, as Nic suggests.

>Indeed if the firewall policies are really brain-damaged then the most 
>effective way to convince people of this is to let things break rather 
>than working around their brain damage.

This is unfortunately the reality of the web where "should" and "does" are
often mismatched.  Spend some time on the WHATWG list debating Ian Hickson
if you don't believe me.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

>> REST-AHAH cuts the methods down to GET and POST 
(and OPTIONS and HEAD too I guess).
 
Just for my edification, what does "AHAH" stand for?
 
-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[ Attachment content not displayed ]

> Now I have another problem,
> I don't know how to handle opaque URIs in Apache. I want /myserver/products/1/ to run an  index.php and /myserver/products/ to run the same index.php etc.
> Do you know how can I do it without copy this file in every directory?
> I know that it is not an Apache mailing list but I believe that most of you have solve this problem and probably can help me :)

Just drop these lines in an .htaccess file at at, for example, /myserver/.

RewriteEngine On
RewriteBase /base/url/for/rewriting
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*) /path/to/file.php [L]

Chase Urich
(Sorry for the double Stelios, forgot to adjust the reply to go to the group)

On 1/2/07, Mike Schinkel <mikeschinkel@...> wrote:
> [snip]
> Just for my edification, what does "AHAH" stand for?

See my bookmarks at http://del.icio.us/alan.dean/ahah

On 1/2/07, Stelios Eliakis <eliakis@...> wrote:
> I have never heard mod_rewrite :)
> Is something trivial? Difficult? Can you give me any tip?

http://www.google.com/search?q=mod_rewrite

>> Stelios Eliakis wrote:
>> I have never heard mod_rewrite :)
>> Is something trivial? Difficult? Can you give me any tip?

Not hard, if you know regular expressions. If not, beware. ;-)
 
Well, I wrote an writeup about clean URLs for Mediawiki using
mod_rewrite[1].
But just Google it[2]; you should find far more than enough to go on.
If not, just ask.
 
-- 
-Mike Schinkel 
http://www.mikeschinkel.com/blogs/ 
http://www.welldesignedurls.org/ 

[1] http://wiki.welldesignedurls.org/Clean_Urls_for_MediaWiki
[2] http://www.google.com/search?q=mod_rewrite

Alan Dean wrote:
> Mike Schinkel wrote:
>> Just for my edification, what does "AHAH" stand for?
> See my bookmarks at http://del.icio.us/alan.dean/ahah
<http://del.icio.us/alan.dean/ahah> 

Thanks.  Jeesh, another acronym/meme! 	And to this I thought that AHA was
just called POX! [1] 

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] Plain Old XML

On 12/31/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> On Sat, 2006-12-30 at 19:08 -0600, Hugh Winkler wrote:
> > On 12/30/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > > I'm not sure who you think will interpret this form on the client
> > side.
> > > You see, the thing is that the atom document format is already a
> > form. A
> > > client has already received the form by being programmed in a
> > particular
> > > way, and is now submitting the form. It knows what information
> > should be
> > > placed in each of the named fields. It knows how to construct the
> > end
> > > document.
> > Ah, but it is a standard form for all servers -- not for my particular
> > server app. And to know what kind of form to submit, you read a spec
> > -- you did not GET the description from the server. It's all baked in
> > at design time.
>
> Exactly. It has been agreed ahead of time.

That's the problem --- "ahead of time" rather than dynamically at run time.

>Now, I can just send my POST
> request and know that the server understands a useful subset of what I
> am sending them.

Not sure how you would know it understands a useful subset. You won't
have the slightest idea what parts of your document it understands, or
doesn't. doesn't handle multiple authors? Can only accept text/plain
for <title>?

>
> What you are suggesting is that I first need to obtain a schema document
> (which you are calling a form)

A schema document is not a form. Maybe we should stay away from XML
for a moment. Think HTML form...  which is a little "program" telling
the UA how to serialize a submission.

I didn't mention RDF forms[1]... but I should have.

> to see if the server is actually
> understanding only a subset of the atom vocabulary.

Not a subset... could be a superset.

> Then I need to
> customize my content to conform to this subset. As a machine, I don't
> have any good way of doing that.

See, you have this problem anyway. If you are sending a server stuff
it doesn't understand, or not enough stuff, your application will
fail.

With forms, at least, your application knows "Hey, I don't know how to
fill out this required field". Same as a human would using an HTML
form. Your client can report that to a human for correction.

Atom (and any application protocol based on exchanging known document
types) has to trade off between exhaustively specifying application
behavior and exhaustively specifying failure handling.

>If I come up to a server that has
> support for an unexpectedly small subset of atom, I then have to
> customize my content in an unexpected way.

It is better for you to do the customizing. TTake the example of a
server that simply cannot honor text/html or application/xhtml+xml in
the title field. It can only handle text/plain. Atom protocol says
nothing at the moment about this situation, except that the server can
change your POSted data as it needs to. So presently my server either
a) rejects your submission or b) stores it as text/plain.  Better
would be for your client to receive an Xform with a constraint
specifiying "text/plain" only -- then, if the user had any imprtant
rich content they wanted to put in the title, they can at least try to
compensate.


>That is to say, I way that
> noone programmed me to customise my content in :)
>
Well, you would have programmed it from this pov, so you would have
handled these exceptional situations.

> The server, on the other hand, is in a good position to customise the
> content. It knows which subset of atom it understands, and it knows what
> atom is generally. It knows multiple authors might be required, so is in
> a position to either model those multiple authors or use an algorithm to
> select an author for its model from the available list.


See above. Yes, you are describing the undesirable behavior the
current APP forces you into.

>
> > What I proposed is that the form delivered by a server have just the
> > elements that make sense for the server. My server might not know what
> > to do with a <source> element. Using the standard "form", my server
> > has to have handling in place if you submit a <source> element, and it
> > has to describe to you the problem if you do submit <source> and my
> > server rejects it.
>
> All atom elements make sense to the server, even if they don't fit the
> server's internal model.
> The server implements atom, after all.

not so -- the client may submit extgension elements the server isn't aware of.

> What you
> are suggesting is adding an extra message exchange to move the
> complexity of fitting atom into the server's model back to the client.

Yes.

> Neither side is going to be great at solving a model mismatch problem,
> but the client is likely to be downright incapable.

As above: The client is in the best position to take corrective
action, so as to best fulfill its intent.

>If you really want
> to be able to sensibly deal with this class of server you need to encode
> how that class of server behaves into the atom specifications (as you
> suggested was already being done). Then the server will use a
> generally-accepted algorithm to select which author it will use from the
> ones available, and the client will know to put the most important
> author first.
>

Yes... app is prescribing server behavior, not message semantics.

> > > One might argue that the client and server should communicate online
> > > before the client submits data that the server might not accept. In
> > one
> > > of the examples you mentioned earlier the server might not support
> > the
> > > full atom protocol, in that multiple authors may not be supported.
> > To be clear -- whether a server has a model supporting multiple
> > authors is a modeling, not a message exchange protocol, issue.
>
> The server's model doesn't allow for a full fidelity translation of the
> atom protocol. The model doesn't allow the full protocol to be
> understood.
>
> > > As
> > > such, the server might be able to publish a document that indicated
> > a
> > > subset of the atom format that is usable.
> > >I suggest that while a
> > > document format could be produced to communicate which subset is
> > > important, the cost would likely outweigh the value. Certainly,
> > allowing
> > > for additional elements in the form would not be meaningful to a
> > client
> > > without further specificaiton as to what those elements mean. Any
> > > additions of this kind would likely require code changes to the
> > client.
> >
> > Well I was focusing on what clients POST to servers, but it seemed
> > like you began that para talking about what servers publish?
> >
> > In the case of servers describing what clients can send to them, that
> > would just be the Xform, so I'm not clear how the cost outweighs the
> > value -- it seems simple enough in this case.
>
> Hrrm... why not xml schema? Why not relax ng? Why not another format?
>

Schema != Form, but yeah, another kind of form ... RDF form...


> Naming a particular specification doesn't really help. A standardisation
> process still has to take place to achieve widespread acceptance.
>

It's already in place. Programs understand the meanings of Atom XML
elements. So when presented with an Xform model specifying those
elements, the client app kknows how to populate those fields.

> Your server can still offer an xform or a HTML form to allow new atom
> entries to be created by humans. That needs no further standardisation
> to occur. However, machine to machine communications is best and
> simplest when the specification can be treated as the form that needs to
> be filled out and understood.

Well heck... if you believe that, then RPC is a good approach... it's
all spelled out for the client programmers at design time.

>Additional negotiation between client and
> server reduces the value of the standard and increases complexity
> everwhere.
>

Forms made the web adaptive. Go to any airline reservation web site.
They're all the same, but different too. They mostly do the same
things, but Orbitz offers packages with hotels and cars, while Delta
offers connections with partner airlines, and  Priceline won't let you
see the itinerary. There's some shared vocabulary among all those
sites but varying behavior. If the airlines standardize their
vocabulary for forms, you could program a client to interact,
adaptively, with all those sites. But you could not constrain
Priceline's app to squeeze into the same behavior model as Delta's.
And you shouldn't -- you should encourage diversity among web apps, as
has been successful on the web to date.


Hugh
[1] http://www.markbaker.ca/2003/05/RDF-Forms/

On Jan 2, 2007, at 3:57 AM, Mike Schinkel wrote:
> Steve G. Bjorg wrote:
> > Mike Schinkel wrote:
> > > > Ah yes, the ugly '@' prefix. It's to avoid naming clashes  
> between
> > > > built-in and custom URIs.
> > >
> > > I definitely wouldn't use something that requires encoding.
> >
> > It doesn't. According to [1] (section 3.3), the '@' character is
> > legal in the URI path and does not require escaping.
> > [1] http://www.ietf.org/rfc/rfc2396.txt
>
> I didn't check rfc 2396, but rfc 3986 obsoletes it. Reading from  
> "Reserved
> Characters" section[1] it appears that you should percent encode  
> the '@'
> character, but I could be misreading. Can anyone on the list with more
> experience tell me if I'm interpreting it incorrectly, and if so why?

A URI generator should percent-encode reserved characters when they
are not being used as delimiters, so that other layers that do use
them as delimiters can treat them specially without misinterpreting
normal data (e.g., a name that just happens to start with @ would
be encoded, whereas the delimiter used by Dream would not).

In other words, Dream is using a reserved character correctly.
Whether or not @ is the best choice for that reserved character
is a long story and probably depends on what URIs are allowed
(some use @ in the path for other things) and whether or not it
interfaces with XPath processing (which uses @ for attribute names).

....Roy

On Jan 2, 2007, at 9:19 AM, Mike Schinkel wrote:
> Walden Mathews wrote:
> > Maintaining multiple URIs for the same resource is not
> > best practice. For the same reason you want uniformity in
> > methods, you want one preferred URI for identifying a
> > resource. The server should redirect requests for other
> > equivalent URIs to the preferred one. Althought that's not
> > quite what you are asking, I think it is the answer.
>
> I'm curious why you make the above statement. Is there a W3C  
> finding that documents this, or some other paper? I've been doing a  
> significant amount of research on URLs and URI best practices in  
> the past 3+ months and have found nothing like this (though I could  
> have missed it.)

It is inherent in the power laws of economics, the network effect
of Metcalfe, the PageRank of Google, and I am sure it is mentioned
somewhere in webarch.  A gave a presentation to the W3C Tech Plenary
that described it using a single graph that is bisected when other
sites start referring to two separate URIs for the same resource.

When the best resources on the Web are identified by the sites
that link to them, introducing multiple URIs for the same resource
has the effect of exponentially decreasing its perceived value.

It also decreases cache efficiency, but resource owners don't
respect that as much as the PageRank argument.

....Roy

On Jan 2, 2007, at 7:15 AM, Chris Burdess wrote:
> Benjamin Carlyle wrote:
> > If I PUT several times to <http://example.com/mydocument>, is it
> > important to me that the <http://example.com/mydocument;1>,
> > <http://example.com/mydocument;2>, and <http://example.com/ 
> mydocument;3>
> > resources are created? My operation has succeeded. Whatever else the
> > server chooses to do with my submission is up to it. I don't see any
> > need to redirect a client to a specific new document version in  
> order to
> > allow their PUT operation to proceed.
>
> It does seem to be a bit of a bone of contention. If we assume that
> /mydocument *does* change, i.e. that it is equivalent to
> /mydocument;current or maybe /mydocument?revision=current , and always
> reflects the state of the last change, then the PUT to /mydocument is
> only idempotent with respect to /mydocument and not to the entire
> namespace. This is a problem since RFC 2616 defines an idempotent  
> method
> in terms of its side-effects not its direct effects, if you see what I
> mean.

*sigh*

Just ignore the definition of idempotent in RFC 2616.  Anything
specified in HTTP that defines how the server shall implement the
semantics of an interface method is wrong, by definition.  What
matters is the effect on the interface as expected by the client,
not what actually happens on the server to implement that effect.

....Roy

Mike,

Thanks for your comments.  A couple of followup questions for the list:

Mike Dierken wrote:
> First, it looks like some folks spent a good deal of time writing
> extensive documentation - that's very nice.
> Here are a couple comments:
>
> 1 Application ID
> The application-id is placed in the URI, but it does not appear to
> actually change what data is being accessed - it's not part of a data
> identifier. An alternative would be to use the Authorization request
> header (where username/passwords normally go) in order to specify the
> application ID.
>  Pro: closer to protocol specification for authentication
>  Pro: common URI for a resource across applications provide more
> chances for caching, hyperlink references, etc.
>  Con: logging/processing of requests on the server would need to
> examine more than just the URI (hopefully this isn't a challenge for
> your framework)
>   
The application ID is actually a separate thing from the user ID and is 
more parallel to User-Agent.  I think the user credentials would be the 
information passed in the Authorization: header, no?

Motivation: The application ID is however related to authorization; it's 
the identity of a third party which is leveraging this API on behalf of 
an actual user.  For example a mashup site would have a unique 
application ID.  This lets us do tracking of who's using the APIs, and 
also lets us do rate limiting if necessary (say, if someone wrote a 
virus and attempted a DDOS attack -- obtaining an application ID is a 
manual process).  It's not intended to really be a secure method of 
authorization, any more than User-Agent is, but useful nonetheless.
> ...
>
> 3 User Sign In
> Considering security and privacy of end-users is very good. However,
> the approach of 'signing in' seems odd, complex and not at all a
> service API. Specifically, the authentication specification describes
> only how to redirect a user's web browser to a particular page. For
> non-browser based applications, this would be unhelpful.
> Essentially, the user's username/password is submitted via HTTPS and a
> response has a Location: header with a URI with an auth=[something]
> query term. That auth value is then used to generate a token that
> (temporarily) identifies the user, which is then later used in other
> user-specific requests.
>   
Yes, authentication is a problem.  I believe the above is a consequence 
of wanting to be able to control what the end user sees during 
authentication, and up to the point of getting an auth token is intended 
to be the same for all AOL APIs.   For example, some applications or 
user accounts may require two factor authentication, or captcha 
challenge.  (I believe that GData does something very similar.)  There 
are also complex issues involved with signing out and timing out.  
Finally, there is also an intent to be able to let a user control what 
data is provided to different services (identified by application ID, 
again) -- something do-able with a token but not with username/password 
combinations.  The latter seems to be the current default for composing 
web services but it's not a very good one.  (OpenID is another potential 
option but of course that also involves a round trip through a web page.)

Authentication is a very challenging topic and I think it's one that is 
a going to be a gating factor in deployment of more sophisticated web 
services of all kinds.  Note that the most used web services today don't 
require authentication, and I think that's partly because there isn't a 
really good answer for this right now.  Any suggestions?

-- 
Abstractioneer <http://feeds.feedburner.com/aol/SzHO>John Panzer
System Architect
http://abstractioneer.org

John Panzer <jpanzer@...> writes:

> Authentication is a very challenging topic and I think it's one that is 
> a going to be a gating factor in deployment of more sophisticated web 
> services of all kinds.  Note that the most used web services today don't 
> require authentication, and I think that's partly because there isn't a 
> really good answer for this right now.  Any suggestions?

I can see where you're coming from but I can't fully agree.

RESTfull authentication is possible (I'm doing it... my app will be
announced here this week!)

Also, fully secure authentication is simply client certs. Client certs
are great, they really work. Ok. They do require a lot of work. But
it's good scalable stuff once it's done.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

In 2616*, I interpret "side effects" to mean resource state changes,
as opposed to values returned in the response.  I think Chris is 
interpreting
"side effects" to mean changes to resources other than the target
of the request.  Is there any more to the issue than that?  Or is my
interpretation wrong?

Walden

* section 9.1.2 specifically

----- Original Message ----- 
From: "Roy T. Fielding" <fielding@...>
To: "Chris Burdess" <dog@...>
Cc: "REST Discuss" <rest-discuss@yahoogroups.com>
Sent: Tuesday, January 02, 2007 3:16 PM
Subject: Re: [rest-discuss] More on versioned resources


: On Jan 2, 2007, at 7:15 AM, Chris Burdess wrote:
: > Benjamin Carlyle wrote:
: > > If I PUT several times to <http://example.com/mydocument>, is it
: > > important to me that the <http://example.com/mydocument;1>,
: > > <http://example.com/mydocument;2>, and <http://example.com/
: > mydocument;3>
: > > resources are created? My operation has succeeded. Whatever else the
: > > server chooses to do with my submission is up to it. I don't see any
: > > need to redirect a client to a specific new document version in
: > order to
: > > allow their PUT operation to proceed.
: >
: > It does seem to be a bit of a bone of contention. If we assume that
: > /mydocument *does* change, i.e. that it is equivalent to
: > /mydocument;current or maybe /mydocument?revision=current , and always
: > reflects the state of the last change, then the PUT to /mydocument is
: > only idempotent with respect to /mydocument and not to the entire
: > namespace. This is a problem since RFC 2616 defines an idempotent
: > method
: > in terms of its side-effects not its direct effects, if you see what I
: > mean.
:
: *sigh*
:
: Just ignore the definition of idempotent in RFC 2616.  Anything
: specified in HTTP that defines how the server shall implement the
: semantics of an interface method is wrong, by definition.  What
: matters is the effect on the interface as expected by the client,
: not what actually happens on the server to implement that effect.
:
: ....Roy
:
:
:
: __________ NOD32 1953 (20070102) Information __________
:
: This message was checked by NOD32 antivirus system.
: http://www.eset.com
:
: 

Mike Schinkel wrote:

> The internal admins configuring the firewall in many places are clueless
> (believe me, I ran a business for a while where that was truly the case but
> I couldn't afford to hire anyone better. And it will be the case in many
> small to medium size businesses.)

The market will deal with businesses like that. I don;t see why 
genuinely competent organizations should have to put up with bad 
architectures to support their pointy-haired competitors.

It seems suspicious to me that these purported admins who are so 
incompetent they can't properly manage PUT and DELETE knew enough to 
block these methods in the first place. I suspect what may really be 
going on is unchanged defaults in the firewalls and proxy servers. If 
indeed that's the case then it's much easier to fix the problem at its 
source by educating a relatively small number of proxy and firewall vendors.

Indeed all you may need to do when a customer tells you your system 
seems broken is say, "Oh, you're using proxy X? That's broken and 
non-spec compliant. Use proxy Y instead and all will be fine."

Of course, this is not a binary situation. Some will fix their systems 
and some won't. My experience leads me to believe that when you insist 
on spec compliance, more people will fix their systems and come into 
compliance than won't. You will lose a few percent. However if you try 
and support all the broken and brain damaged networks out there, you do 
  far more damage to everyone. You end up hurting the compliant 
customers to support the noncompliant ones in a dozen different, subtle 
ways. Maximum net benefit to all involved is achieved by jettisoning the 
truly incompetent organizations that will not and cannot learn the 
proper way to do things.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

I think the answer you're looking for is found in the explanation
often given about GET and side-effects; that the client didn't request
them and so can't be held accountable.  Similarly, from the POV of
this thread, if a server non-idempotently "versions" a resource on a
PUT, the client isn't requesting that action, the server just decided
to do it, and therefore it's not a violation of PUT semantics ... as
long as the server also sets the state of the targetted resource to
that represented in the request, of course.

I've understood this distinction for some time, but it still catches
me on occasion...

Mark.

On 1/2/07, Walden Mathews <waldenm@...> wrote:
> In 2616*, I interpret "side effects" to mean resource state changes,
> as opposed to values returned in the response.  I think Chris is
> interpreting
> "side effects" to mean changes to resources other than the target
> of the request.  Is there any more to the issue than that?  Or is my
> interpretation wrong?
>
> Walden
>
> * section 9.1.2 specifically
>
> ----- Original Message -----
> From: "Roy T. Fielding" <fielding@...>
> To: "Chris Burdess" <dog@...>
> Cc: "REST Discuss" <rest-discuss@yahoogroups.com>
> Sent: Tuesday, January 02, 2007 3:16 PM
> Subject: Re: [rest-discuss] More on versioned resources
>
>
> : On Jan 2, 2007, at 7:15 AM, Chris Burdess wrote:
> : > Benjamin Carlyle wrote:
> : > > If I PUT several times to <http://example.com/mydocument>, is it
> : > > important to me that the <http://example.com/mydocument;1>,
> : > > <http://example.com/mydocument;2>, and <http://example.com/
> : > mydocument;3>
> : > > resources are created? My operation has succeeded. Whatever else the
> : > > server chooses to do with my submission is up to it. I don't see any
> : > > need to redirect a client to a specific new document version in
> : > order to
> : > > allow their PUT operation to proceed.
> : >
> : > It does seem to be a bit of a bone of contention. If we assume that
> : > /mydocument *does* change, i.e. that it is equivalent to
> : > /mydocument;current or maybe /mydocument?revision=current , and always
> : > reflects the state of the last change, then the PUT to /mydocument is
> : > only idempotent with respect to /mydocument and not to the entire
> : > namespace. This is a problem since RFC 2616 defines an idempotent
> : > method
> : > in terms of its side-effects not its direct effects, if you see what I
> : > mean.
> :
> : *sigh*
> :
> : Just ignore the definition of idempotent in RFC 2616.  Anything
> : specified in HTTP that defines how the server shall implement the
> : semantics of an interface method is wrong, by definition.  What
> : matters is the effect on the interface as expected by the client,
> : not what actually happens on the server to implement that effect.
> :
> : ....Roy
> :
> :
> :
> : __________ NOD32 1953 (20070102) Information __________
> :
> : This message was checked by NOD32 antivirus system.
> : http://www.eset.com
> :
> :
>
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On Jan 2, 2007, at 4:42 PM, Mark Baker wrote:
> I think the answer you're looking for is found in the explanation
> often given about GET and side-effects; that the client didn't request
> them and so can't be held accountable. Similarly, from the POV of
> this thread, if a server non-idempotently "versions" a resource on a
> PUT, the client isn't requesting that action, the server just decided
> to do it, and therefore it's not a violation of PUT semantics ... as
> long as the server also sets the state of the targetted resource to
> that represented in the request, of course.
>
> I've understood this distinction for some time, but it still catches
> me on occasion...

Yes, that's it.  We have to keep dancing around that bush because
terminology is a committee-driven process.  Everyone has an opinion
and so no opinion is spec'd consistently.

....Roy

Roy T. Fielding wrote:
> > Steve G. Bjorg wrote:
> > > Mike Schinkel wrote:
> > > > > Ah yes, the ugly '@' prefix. It's to avoid naming clashes
> > between
> > > > > built-in and custom URIs.
> > > >
> > > > I definitely wouldn't use something that requires encoding.
> > >
> > > It doesn't. According to [1] (section 3.3), the '@' character is 
> > > legal in the URI path and does not require escaping.
> > > [1] http://www.ietf.org/rfc/rfc2396.txt
> >
> > I didn't check rfc 2396, but rfc 3986 obsoletes it. Reading from 
> > "Reserved Characters" section[1] it appears that you should percent 
> > encode the '@'
> > character, but I could be misreading. Can anyone on the 
> list with more 
> > experience tell me if I'm interpreting it incorrectly, and 
> if so why?
> 
> A URI generator should percent-encode reserved characters 
> when they are not being used as delimiters, so that other 
> layers that do use them as delimiters can treat them 
> specially without misinterpreting normal data (e.g., a name 
> that just happens to start with @ would be encoded, whereas 
> the delimiter used by Dream would not).
> 
> In other words, Dream is using a reserved character correctly.
> Whether or not @ is the best choice for that reserved 
> character is a long story and probably depends on what URIs 
> are allowed (some use @ in the path for other things) and 
> whether or not it interfaces with XPath processing (which 
> uses @ for attribute names).

Interesting. Hmmm.  I'm going to have to mull on that one a bit. Is it a
being used as a delimiter because it denotes a special class of URLs? That
would not have occurred to me. I keep learning something new on this list
everyday...

Thanks.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Roy T. Fielding wrote:
> On Jan 2, 2007, at 9:19 AM, Mike Schinkel wrote:
> > Walden Mathews wrote:
> > > Maintaining multiple URIs for the same resource is not best 
> > > practice. For the same reason you want uniformity in methods, you 
> > > want one preferred URI for identifying a resource. The 
> server should 
> > > redirect requests for other equivalent URIs to the preferred one. 
> > > Althought that's not quite what you are asking, I think it is the 
> > > answer.
> >
> > I'm curious why you make the above statement. Is there a 
> W3C finding 
> > that documents this, or some other paper? I've been doing a 
> > significant amount of research on URLs and URI best 
> practices in the 
> > past 3+ months and have found nothing like this (though I 
> could have 
> > missed it.)
> 
> It is inherent in the power laws of economics, the network 
> effect of Metcalfe, the PageRank of Google, and I am sure it 
> is mentioned somewhere in webarch.  A gave a presentation to 
> the W3C Tech Plenary that described it using a single graph 
> that is bisected when other sites start referring to two 
> separate URIs for the same resource.
> 
> When the best resources on the Web are identified by the 
> sites that link to them, introducing multiple URIs for the 
> same resource has the effect of exponentially decreasing its 
> perceived value.
> 
> It also decreases cache efficiency, but resource owners don't 
> respect that as much as the PageRank argument.

Can you please address the usability issue I raised?  You addressed the
technical issues, but not the usability issues.

Wouldn't this argue for additional authoritative metadata in HTTP headers
and HTML <head> elements that both browsers and search engines can use to
address the issues you raise?

FYI, I've been doing a lot of research in this area, reading everything I
could find the web and more on the subject, and have plans to publishing a
lot of comments regarding this as well as and make calls for this metadata
on the WDUI blog [1] over the next year.  I've even come across documents
you've written that I believed would imply such a thing (but their URLs are
not readily available; I still have lots of information sorting and
classifying left to do. But I will reference those writing when I publish.)
Hopefully you'll agree there is a need for better metadata, especially from
web apps (blogs, wikis, CMS systems, etc.) that can correctly manage such
metadata.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://blog.welldesignedurls.org/

Steve G. Bjorg wrote:
> I've created a short tutorial on REST and some common 
> resource/service patterns. The tutorial is based on my 
> experience with designing the API for our DekiWiki 
> application [1].
>
> I would welcome feedback on the accuracy of the content. 
> The tutorial will be used to introduce developers to REST 
> and establish a common framework for designing services.
> http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us 

WHOA!  I opened it and went to click your "Print Page" and up popped THE
MOST AWESOME print dialog I have EVER SEEN on any website, and I print a
lot.  NICE!

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
P.S. Mind if I steal the idea from you?  Man, I'd love to see that a
WordPress plugin.

> The application ID is actually a separate thing from the user ID and is
more parallel to User-Agent.  
> I think the user credentials would be the information passed in the
Authorization: header, no? 
Yes, credentials go in the Authorization header. I'm not sure have distince
user-agent values is useful in this case. The Authorization header can
easily contain both the application-id and some transient token authorizing
that request. The server could reject the request on an application-wide
basis as well as per-resource (for example, if a user disallows a particular
application from mucking with their stuff).

> Finally, there is also an intent to be able to let a user control what
data is provided to different services 
> (identified by application ID, again) -- something do-able with a token
but not with username/password combinations.  
What if the request contained the username/password of the application, not
the end-user. And the user could allow/deny access on a per-application
basis. The user would not need to re-login for each and every third-pary
application (which might make them de-sensitized to guarding their
password).



________________________________

	From: John Panzer [mailto:jpanzer@...] 
	Sent: Tuesday, January 02, 2007 12:58 PM
	To: Mike Dierken
	Cc: Nic James Ferrier; rest-discuss@yahoogroups.com
	Subject: Re: [rest-discuss] AOL and REST?
	
	
	Mike,
	
	Thanks for your comments.  A couple of followup questions for the
list:
	
	Mike Dierken wrote: 

		First, it looks like some folks spent a good deal of time
writing
		extensive documentation - that's very nice.
		Here are a couple comments:
		
		1 Application ID
		The application-id is placed in the URI, but it does not
appear to
		actually change what data is being accessed - it's not part
of a data
		identifier. An alternative would be to use the Authorization
request
		header (where username/passwords normally go) in order to
specify the
		application ID.
		 Pro: closer to protocol specification for authentication
		 Pro: common URI for a resource across applications provide
more
		chances for caching, hyperlink references, etc.
		 Con: logging/processing of requests on the server would
need to
		examine more than just the URI (hopefully this isn't a
challenge for
		your framework)
		  

	The application ID is actually a separate thing from the user ID and
is more parallel to User-Agent.  I think the user credentials would be the
information passed in the Authorization: header, no?
	
	Motivation: The application ID is however related to authorization;
it's the identity of a third party which is leveraging this API on behalf of
an actual user.  For example a mashup site would have a unique application
ID.  This lets us do tracking of who's using the APIs, and also lets us do
rate limiting if necessary (say, if someone wrote a virus and attempted a
DDOS attack -- obtaining an application ID is a manual process).  It's not
intended to really be a secure method of authorization, any more than
User-Agent is, but useful nonetheless.
	

		...
		
		3 User Sign In
		Considering security and privacy of end-users is very good.
However,
		the approach of 'signing in' seems odd, complex and not at
all a
		service API. Specifically, the authentication specification
describes
		only how to redirect a user's web browser to a particular
page. For
		non-browser based applications, this would be unhelpful.
		Essentially, the user's username/password is submitted via
HTTPS and a
		response has a Location: header with a URI with an
auth=[something]
		query term. That auth value is then used to generate a token
that
		(temporarily) identifies the user, which is then later used
in other
		user-specific requests.
		  

	Yes, authentication is a problem.  I believe the above is a
consequence of wanting to be able to control what the end user sees during
authentication, and up to the point of getting an auth token is intended to
be the same for all AOL APIs.   For example, some applications or user
accounts may require two factor authentication, or captcha challenge.  (I
believe that GData does something very similar.)  There are also complex
issues involved with signing out and timing out.  Finally, there is also an
intent to be able to let a user control what data is provided to different
services (identified by application ID, again) -- something do-able with a
token but not with username/password combinations.  The latter seems to be
the current default for composing web services but it's not a very good one.
(OpenID is another potential option but of course that also involves a round
trip through a web page.)
	
	Authentication is a very challenging topic and I think it's one that
is a going to be a gating factor in deployment of more sophisticated web
services of all kinds.  Note that the most used web services today don't
require authentication, and I think that's partly because there isn't a
really good answer for this right now.  Any suggestions?
	
	
	-- 
	Abstractioneer <http://feeds.feedburner.com/aol/SzHO> John Panzer
	System Architect
	http://abstractioneer.org
	

I think that authenticating a client application isn't the hard problem here
- I think it's the end-user authorizing that particular application to muck
about with their data. Causing the user to re-enter username/password in a
web page for each application implicitly is granting that application
access. The 'shared secret' part of AOLs video service APIs is how they
verify that application is authentic.



> -----Original Message-----
> From: Nic James Ferrier [mailto:nferrier@...] 
> Sent: Tuesday, January 02, 2007 2:01 PM
> To: John Panzer
> Cc: Mike Dierken; rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] AOL and REST?
> 
> John Panzer <jpanzer@...> writes:
> 
> > Authentication is a very challenging topic and I think it's 
> one that 
> > is a going to be a gating factor in deployment of more 
> sophisticated 
> > web services of all kinds.  Note that the most used web 
> services today 
> > don't require authentication, and I think that's partly 
> because there 
> > isn't a really good answer for this right now.  Any suggestions?
> 
> I can see where you're coming from but I can't fully agree.
> 
> RESTfull authentication is possible (I'm doing it... my app 
> will be announced here this week!)
> 
> Also, fully secure authentication is simply client certs. 
> Client certs are great, they really work. Ok. They do require 
> a lot of work. But it's good scalable stuff once it's done.
> 
> --
> Nic Ferrier
> http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

> This introduction will cover some basics of HTTP [...]
You probably should mention that REST does not mean "HTTP" and mention why
you chose to talk about HTTP (like, it display many of the characteristics
described by the REST style).

> Compare this to mounted network drives, whose names have no way of being
resolved by a recipient. 
Huh? I would need an explanation of how that's similar, so this could be
clarified or replaced with something more understandable.

> Similarly, we can also query a complex resource, such as a blog, to get
parts of the data:
This isn't querying a resource, it simply /is/ a resource. You might say
something like a resource can represent complex information like "all the
blog comments after a particular timestamp written by 'anonymous' ". The
client doesn't need to know just how complex things could be for the server
- it just does a GET.

> All data resources support GET, but not all behavioral resources do. 
What's a "data resource" compared to "behavioral resource" - you might
rephrase that to say that some resources are read-only.

> While a GET request cannot have side-effects, it can return only parts of
the resource.  
> This means that GET is both an atomic read, as well as a query operation.
This is not correct - GET does not return parts of a resource. At least, not
the way you suggest with query terms.
You might want to describe that a GET could be a simple static file or a
complex query operation - both are simply retrievals of data.

> If two PUT operations occur simultaneously, one of them will win and
determine the final state of the resource. 
What happens to the other one? I think that both win. REST gives rise to all
sorts of win-win situations.

> In the case of two simultaneous DELETE operations, one of them may fail
since the resource 
> will have already been deleted.
Nope. It's important to realize that /both/ succeed. There should be no
error code. The protocol does not assume a "locate object or fail, activate
object or fail, invoke method on object" - it just says "make sure the
resource is gone when the request completes". An absent resource is just as
gone as a recently deleted one.

> The POST operation is very generic and no specific meaning can be attached
to it. 
There is meaning associated with it, and unique aspects regarding
repeatability and caching.

> In general, use POST when only a subset of a resource needs to be modified
and it cannot be accessed 
> as its own resource; or when the equivalent of a method call must be
exposed.
Rather than suggesting a generic method calls is appropriate via POST,
perhaps you could narrow it down to modification operations that don't fit
into PUT or DELETE.

> We can also update individual properties of the entry, because they are
exposed as nested resources. 
There isn't a concept of a 'nested resource'. And this example only works
because the server implements it that way, it's not part of REST or HTTP (or
even most Web server frameworks unfortunately). And there is no requirement
that the second resource that is the 'property of the entry' use a URI with
paths - it could just as easily be:
 PUT http://myserver/myaddressbook/johndoe?prop=27
 PUT http://myserver/myaddressbook/phones?user=johndoe&type=work



> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Steve G. Bjorg
> Sent: Monday, January 01, 2007 9:28 PM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Request for feedback: REST for the Rest of Us
> 
> I've created a short tutorial on REST and some common 
> resource/service patterns.  The tutorial is based on my 
> experience with designing the API for our DekiWiki application [1].
> 
> I would welcome feedback on the accuracy of the content.  The 
> tutorial will be used to introduce developers to REST and 
> establish a common framework for designing services.
> http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us
> 
> Thanks in advance for taking a look at it.
> 
> 
> Cheers,
> 
> - Steve
> 
> [1] http://doc.opengarden.org/DekiWiki_API/Reference/DekiWiki
> 
> --------------
> Steve G. Bjorg
> http://www.mindtouch.com
> http://www.opengarden.org
> 
> 
> 
>  
> Yahoo! Groups Links
> 
> 
> 

S. Mike Dierken wrote:

> ...
>
>>Finally, there is also an intent to be able to let a user control what data is provided to different services (identified by application ID, again) -- something do-able with a token
>>    
>>
>but not with username/password combinations.  
>
>What if the request contained the username/password of the application, not
>the end-user. And the user could allow/deny access on a per-application
>basis. The user would not need to re-login for each and every third-pary
>application (which might make them de-sensitized to guarding their
>password).
>
>  
>
This is equivalent to giving control over both authentication and 
authorization to third parties; we'd have to establish a trust 
relationship, and likely a business relationship, with every third party 
to make this work.  It's not a very scalable solution, I think.  Note 
that the third party would still need to at least pass in an additional 
user ID recognizable by our system in order to deal with per-user data 
(like my photos or bookmarks or ...).

-- 

Abstractioneer <http://feeds.feedburner.com/aol/SzHO>John Panzer
System Architect
http://abstractioneer.org

On Tue, 2007-01-02 at 12:19 -0500, Mike Schinkel wrote:
> Walden Mathews wrote:
> > Maintaining multiple URIs for the same resource is not
> > best practice. For the same reason you want uniformity in
> > methods, you want one preferred URI for identifying a
> > resource. The server should redirect requests for other
> > equivalent URIs to the preferred one. Althought that's not
> > quite what you are asking, I think it is the answer.
> Consider another set of URLS:
> http://www.mycarsite.com/{make}/{model}/{year}/
> But it's also logical to have:
> http://www.mycarsite.com/{year}/{make}/{model}/
> Or even:
> http://www.mycarsite.com/{make}/{year}/{model}/

They aren't the same resource. They are three different resources that
demarcate the same state :)

In practice you will want a "permalink" that can be bookmarked
consistently and referred to consistently elsewhere. The data from that
resource might be available elsewhere, but it still has a one true home
that can be used as its identifier. The other resources that refer to
the same state should normally include a link to this permanent home.

Benjamin

Benjamin Carlyle wrote:
> > Consider another set of URLS:
> > http://www.mycarsite.com/{make}/{model}/{year}/
> > But it's also logical to have:
> > http://www.mycarsite.com/{year}/{make}/{model}/
> > Or even:
> > http://www.mycarsite.com/{make}/{year}/{model}/
> 
> They aren't the same resource. They are three different 
> resources that demarcate the same state :)

hehe

> In practice you will want a "permalink" that can be 
> bookmarked consistently and referred to consistently 
> elsewhere. 

Permalink to what?  All three? 

> The data from that resource might be available 
> elsewhere, but it still has a one true home that can be used 
> as its identifier. The other resources that refer to the same 
> state should normally include a link to this permanent home.

I agree with that point,... except.  Not I really do, that had been my
conclusion. But as I look at this example I created, how does one decide
which is canonical?  And since each has different breadcrumbs, they are
arguably different, depending on the use-case for the person bookmarking.

Frankly, I think I have a lot of thinking to do on this issue...

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

On 1/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> On Tue, 2007-01-02 at 12:19 -0500, Mike Schinkel wrote:
>  > Consider another set of URLS:
>  > http://www.mycarsite.com/{make}/{model}/{year}/
>  > But it's also logical to have:
>  > http://www.mycarsite.com/{year}/{make}/{model}/
>  > Or even:
>  > http://www.mycarsite.com/{make}/{year}/{model}/
>
>  They aren't the same resource. They are three different resources that
>  demarcate the same state :)
>

Why aren't they the same resource?

Michael

On Tue, 2007-01-02 at 12:31 -0600, Hugh Winkler wrote:
> On 12/31/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > On Sat, 2006-12-30 at 19:08 -0600, Hugh Winkler wrote:
> > > On 12/30/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > > > I'm not sure who you think will interpret this form on the client
> > > side.
> > > > You see, the thing is that the atom document format is already a
> > > form. A
> > > > client has already received the form by being programmed in a
> > > particular
> > > > way, and is now submitting the form. It knows what information
> > > should be
> > > > placed in each of the named fields. It knows how to construct the
> > > end
> > > > document.
> > > Ah, but it is a standard form for all servers -- not for my particular
> > > server app. And to know what kind of form to submit, you read a spec
> > > -- you did not GET the description from the server. It's all baked in
> > > at design time.
> > Exactly. It has been agreed ahead of time.
> That's the problem --- "ahead of time" rather than dynamically at run time.

What you have to understand here, is that you are trying to replace
human agreement with machine agreement. Humans are good at negotiating
standards like atom. It's a hard problem, but standards get nailed out.
Information producers agree to transform their internal models into the
standard format. Information consumers agree that the standard format is
a suitable source of data for their internal models. Internal models
often have to bend as part of this process, and eventually realign
around a competent standard to be more simliar than they are different.

Machines are not good at negotiation. You give a machine a form to fill
out, and the machine already needs to know how to fill out the form
before it starts. The form says "title", "summary", "content". The
machine already needs an internal model that has those elements. The
form says "don't give me the summary", the client could have code
written to say "only send the subset of the standard which the server
says it can accept". That's as good as you can do.

You can't give a client an arbitrary form that isn't a simple subset and
expect it to know what to do. If the client software wasn't written to
know that only one author might be supported on the other side, it can't
choose which author it should supply any better than the server side.
You are lucky if it can interpret the server's instructions not to
supply more than one at all.

You can't arbitrarily place restrictions on the client as to how it
should fill out its content. The only practical way to do it is to write
a program that the client must run over a standard atom data model in
order to fit the server's point of view. And guess what: That's the same
program you would run on the server side if the client just submitted
the atom document in the first place.

Clients can't deal with unexpected server demands. Server demands are
only expected if they are negotiated between humans, which is to say
they are part of the atom specification. You can't do any better than
what is in the standard by supplying a form.

> >Now, I can just send my POST
> > request and know that the server understands a useful subset of what I
> > am sending them.
> Not sure how you would know it understands a useful subset. You won't
> have the slightest idea what parts of your document it understands, or
> doesn't. doesn't handle multiple authors? Can only accept text/plain
> for <title>?

I know it understands because we agreed on the content through the atom
standardisation process. We agreed that I would send this much and the
server would understand that much. Whether understand means "completely
model" is up to the server. It is free to cut the xhtml out of its
title. It is even free to use the xhtml content as text/plain. That's
its perrogative. What is not in its perrogative is to reject a
well-formed and valid atom document. If it intends to do that it should
not claim to understand atom in the first place.

> > What you are suggesting is that I first need to obtain a schema document
> > (which you are calling a form)
> A schema document is not a form. Maybe we should stay away from XML
> for a moment. Think HTML form...  which is a little "program" telling
> the UA how to serialize a submission.

You are describing the set of valid documents I can submit to you. You
can call it a form if you like, but it is more correctly a schema.

If you are no longer talking about a schema, and are now talking about a
program to transform my atom content into your sub-atom content... then
why aren't you running that program on the server side?

> > to see if the server is actually
> > understanding only a subset of the atom vocabulary.
> Not a subset... could be a superset.

Now you are talking about the client supplying more elements than it
knows how to supply. You are presumably talking about extensions to the
standard, but extensions are standards too. Extensions require human
agreement between client and server in order to be understood.

> > Then I need to
> > customize my content to conform to this subset. As a machine, I don't
> > have any good way of doing that.
> See, you have this problem anyway. If you are sending a server stuff
> it doesn't understand, or not enough stuff, your application will
> fail.

But I have already agreed through the standardisation process with the
server that it will understand my content. My application will only fail
if the server fails to implement the specification.

> With forms, at least, your application knows "Hey, I don't know how to
> fill out this required field". Same as a human would using an HTML
> form. Your client can report that to a human for correction.

It only knows if I write code. I only write code if I have communicated
with the guy who wrote the server about what is permissible. I have
already done this. We called that conversation the atom standardisation
process.

Why do you think a human in the loop can do anything about the failure
to communicate? Are they going to hack on their client application every
time a server says it only understands an unexpectedly-small subset of
atom or demands an extension element be supplied? No... if there is a
human in the loop she will write an email to the server's administrator
to inform him of his bug in failing to implement the specification. It
is not the client's problem. It is the server's problem.

> Atom (and any application protocol based on exchanging known document
> types) has to trade off between exhaustively specifying application
> behavior and exhaustively specifying failure handling.

And exhaustively supporting forwards-compatability for extensions, and
exhaustively trading server and client-side complexity for protocol
features.

> >If I come up to a server that has
> > support for an unexpectedly small subset of atom, I then have to
> > customize my content in an unexpected way.
> It is better for you to do the customizing. TTake the example of a
> server that simply cannot honor text/html or application/xhtml+xml in
> the title field. It can only handle text/plain. Atom protocol says
> nothing at the moment about this situation, except that the server can
> change your POSted data as it needs to. So presently my server either
> a) rejects your submission or b) stores it as text/plain.  Better
> would be for your client to receive an Xform with a constraint
> specifiying "text/plain" only -- then, if the user had any imprtant
> rich content they wanted to put in the title, they can at least try to
> compensate.

No no no.... the client doesn't know how to customise the content. As
the author of the client I relied on the atom specification that says I
can supply a content element and I did. Now your server is telling me it
doesn't understand it and wants a summary element instead? My client is
not written to deal with that. The server can deal with its own
shortcomings, thankyou. If it doesn't understand the protocol it should
stop speaking it.

If the server doesn't understand xhtml in the title, then tough! It
knows that it must be expected to deal with xhtml in the title because
we agreed through the standardisation process that it should be capable.
How it provides that support as the atom spec rightly points out is up
to the server. Maybe it will strip out anything in angle-brackets before
storing the value into its internal title variable. Maybe it will just
use the xhtml content verbatim. That's the server's problem. It isn't
permitted to reject my submission. How is my client supposed to know
that what it needs to do in the face of this dumb server? We already
agreed that xhtml was fine, and now this server wants to go back on
that? Move complexity to me, will you? No thanks. I'll find another
server to talk to. Maybe one that understands xhtml in the title.

> >That is to say, I way that
> > noone programmed me to customise my content in :)
> Well, you would have programmed it from this pov, so you would have
> handled these exceptional situations.

I don't write client software to deal with broken servers that don't
implment the spec. It is up to the server to deal with the problem if it
can't translate my request precisely.

> > The server, on the other hand, is in a good position to customise the
> > content. It knows which subset of atom it understands, and it knows what
> > atom is generally. It knows multiple authors might be required, so is in
> > a position to either model those multiple authors or use an algorithm to
> > select an author for its model from the available list.
> See above. Yes, you are describing the undesirable behavior the
> current APP forces you into.

Quite the opposite. Your suggestion doesn't hold water. The spec
reflects decades of experience in developing protocols that work and can
evolve succesfully for decades to come. Do you think you can do better
without having written software on more than one side of the
client/server fence?

> > > What I proposed is that the form delivered by a server have just the
> > > elements that make sense for the server. My server might not know what
> > > to do with a <source> element. Using the standard "form", my server
> > > has to have handling in place if you submit a <source> element, and it
> > > has to describe to you the problem if you do submit <source> and my
> > > server rejects it.
> > All atom elements make sense to the server, even if they don't fit the
> > server's internal model.
> > The server implements atom, after all.
> not so -- the client may submit extgension elements the server isn't aware of.

And the server is required to ignore them and the client is required to
accept that old servers will ignore them. That's the way extensible
protocols work. If the extension is good it will be supported. If it is
not it will be ignored, sidelined, and eventually forgotten.

> > What you
> > are suggesting is adding an extra message exchange to move the
> > complexity of fitting atom into the server's model back to the client.
> > Neither side is going to be great at solving a model mismatch problem,
> > but the client is likely to be downright incapable.
> As above: The client is in the best position to take corrective
> action, so as to best fulfill its intent.

Show me the code. Your solution requires me to write client-side code
every time a new kind of dumb server is placed on the internet. That
doesn't work. That doesn't scale. Machines can't negotiate, only humans
can... and we already have. If you have anything more to add to that
conversation you had better to do it. Don't try to hold a separate
conversation with my client software. It doesn't know how to hold that
conversation.

> Forms made the web adaptive. Go to any airline reservation web site.
> They're all the same, but different too. They mostly do the same
> things, but Orbitz offers packages with hotels and cars, while Delta
> offers connections with partner airlines, and  Priceline won't let you
> see the itinerary. There's some shared vocabulary among all those
> sites but varying behavior. If the airlines standardize their
> vocabulary for forms, you could program a client to interact,
> adaptively, with all those sites. But you could not constrain
> Priceline's app to squeeze into the same behavior model as Delta's.
> And you shouldn't -- you should encourage diversity among web apps, as
> has been successful on the web to date.

The evolvability of HTML and HTTP are what have been successful on the
web to date. Atom follows the evolvability and agreement model of its
predecessors. Do you really want your web server to have to retrieve a
form from every browser that requests a html page before it can be
returned? When that form says "I don't understand paragraph markers",
what will your web server do to make the content fit?

Benjamin.

On Wed, 2007-01-03 at 05:52 -0500, Mike Schinkel wrote:
> Benjamin Carlyle wrote:
> > > Consider another set of URLS:
> > > http://www.mycarsite.com/{make}/{model}/{year}/
> > > But it's also logical to have:
> > > http://www.mycarsite.com/{year}/{make}/{model}/
> > > Or even:
> > > http://www.mycarsite.com/{make}/{year}/{model}/
> > In practice you will want a "permalink" that can be 
> > bookmarked consistently and referred to consistently 
> > elsewhere. 
> Permalink to what? All three? 

A permalink to the content, as viewed by the server-side.

> > The data from that resource might be available 
> > elsewhere, but it still has a one true home that can be used 
> > as its identifier. The other resources that refer to the same 
> > state should normally include a link to this permanent home.
> I agree with that point,... except. Not I really do, that had been my
> conclusion. But as I look at this example I created, how does one
> decide
> which is canonical? And since each has different breadcrumbs, they are
> arguably different, depending on the use-case for the person
> bookmarking.

The server side can decide what is canonical. We are blessed these days
with the example of the blogosphere, where the canonical url differs
from site to site. Each uses some balance between the needs of the
service provider and the needs of the service consumers.

The client can still bookmark whichever they like, but the server only
guarantees the ongoing existence of the url of its choosing. If the
client wants to refer to the content in a permanent way, it should refer
to it via the permanent link. Even if the server's guarantee is present
on all three urls, the server is still free to provide a "preferred" url
it suggests be used in these references.

> > They aren't the same resource. They are three different resources
> > that demarcate the same state :)
Michael Walter wrote:
> Why aren't they the same resource?

Yes, I was only half-joking. Perhaps cyclically, they are different
resources because they have different urls. They are identified
differently, so the server is permitted to change their content
independently. Only the server knows they demarcate the same state as
each other and will always have the same representations as each other.
Clients are not normally permitted to associate them as equivalent
resource, though the server is permitted to provide assurances they they
are the same through mechanisms such as owl:sameAs.

Benjamin.

What method should I use to implement a preview function in a CMS?

I've got an API like this:

   GET /someresource
   return 200 with the latest version of the resource

   POST /someresource [content] 
   create a new version of /someresource with the specificed content.
   return 201 with the new version subsidiary resource, 
   eg: /someresource/0.11

But what if I want to have a preview of the content before I commit
it?

Right now I've got:

   POST /someresource?preview [content]
   return 200 with what the resource would look like

But I'm unsure if this is right. POST should imply some
representational state transfer and this is not state transfer. It's
just look ahead to state transfer.

   GET /somresource?preview

is no good because I can't send the content.

Any thoughts?
   
-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Wed, 2007-01-03 at 15:08 +0000, Nic James Ferrier wrote:
> What method should I use to implement a preview function in a CMS?
[...]
> Right now I've got:
> 
> POST /someresource?preview [content]
> return 200 with what the resource would look like
> 
> But I'm unsure if this is right. POST should imply some
> representational state transfer and this is not state transfer. It's
> just look ahead to state transfer.

Don't you submit the updated content so the server can render it as a
preview?  Sounds like transferring a representation of the "Preview"
state to me.  This seems fine.
 
-- 
...jsled
http://asynchronous.org/ - a=jsled;b=asynchronous.org;echo ${a}@${b}

Benjamin Carlyle wrote:

> * In REST it is likely that multiple resources will be served from a
> single defined set of state, ie a service. For example an object or a
> set of objects are likely to have several resources associated with  
> them
> that act as the network interface to these objects. I would suggest  
> that
> instead of "Each Dream service (being) a resource", each dream service
> should make a set of resources available.

You're absolutely right: a service can provide as many resources as  
its wants.  I was thinking in terms of implementation since a service  
is instantiated, but that was wrong for this context. I've made note  
of it on the feedback page.

> * Returning a dream blueprint to users of the system doesn't read  
> to me
> as useful. If the blueprint exposure is an internal deployment
> mechanism, this is ok. The blueprint appears to be an internal  
> document
> that allows particular methods on particular resources to be mapped to
> other method invocations on internally-defined objects. This is fine,
> but should not normally be communicated to users of the interface.  
> Users
> should see published lists of URIs that meet particular  
> requirements the
> uses may have. Perhaps a cut-down form of the blueprint would be more
> appropriate than one that exposes internal classes and the like.

The blueprint is used by the framework to instantiate the service.   
So, the primary consumer of the blueprint is the framework.  However,  
it's also used by /@inspect to return a HTML document about the  
service and its features.  This human-readable document makes it easy  
to learn about new services and also provides additional links to  
online documentation.

> * It looks like access to HTML headers and the like may be limited.
> Where is the url returned in a POST's Location header in
> <http://doc.opengarden.org/Dream_SDK/Tutorials/Address_Book>?

That sample was intended for simplicity, not completeness.  The basic  
communication unit is a HTTP message containing the headers and  
body.  Common headers such as ContentType, ContentLength, etc. are  
exposed as properties, but arbitrary headers can also be set via the  
Headers[ ] property.

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Mike,

Thanks a lot for taking the time to read it and provide such detailed
feedback.  I've captured all of it at:
http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us/Feedback

This is really good stuff and catching my mistakes early before I
corrupt others is crucial.  I strive to be part of the solution, not
the problem! ;)


Cheers,

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

I don't understand how this gives control to third parties.
What I read here http://developer.searchvideo.com/RESTAPIAuthSpec.php
indicated that both and application-id and 'shared secret' are provided by
AOL. It appears that requests must provide a 'signature' which is based in
part on that shared secret - the AOL service must also know this shared
secret to authenticate that signature, so it seems that authentication is
performed by the AOL service.
The current approach involves the end user to provide authorization every 60
minutes through the process of displaying the appropriate web pages hosted
by AOL - by not providing their username/password the user essentially does
not authorize access. I was just suggesting that this authorization be more
explicit and the end-user could even see a list of applications and whether
they are authorized or not.
 
> Note that the third party would still need to at least pass in an
additional user ID recognizable by our system 
> in order to deal with per-user data (like my photos or bookmarks or ...).
Yes - that is desired. Some of the documented APIs call this a token:
 http://api.searchvideo.com/apiv3
       ?method=truveo.users.getFavoriteVideos
       &appid=MY_APPID
       &token=USER_TOKEN
       &start=0
       &results=10
       &showRelatedItems=1
       &sig=[signature]
 
 
 


  _____  

From: John Panzer [mailto:jpanzer@...] 
Sent: Tuesday, January 02, 2007 10:37 PM
To: S. Mike Dierken
Cc: 'Nic James Ferrier'; rest-discuss@yahoogroups.com
Subject: Re: [rest-discuss] AOL and REST?


S. Mike Dierken wrote: 

... 

Finally, there is also an intent to be able to let a user control what data
is provided to different services (identified by application ID, again) --
something do-able with a token

    

but not with username/password combinations.  



What if the request contained the username/password of the application, not

the end-user. And the user could allow/deny access on a per-application

basis. The user would not need to re-login for each and every third-pary

application (which might make them de-sensitized to guarding their

password).



  

This is equivalent to giving control over both authentication and
authorization to third parties; we'd have to establish a trust relationship,
and likely a business relationship, with every third party to make this
work.  It's not a very scalable solution, I think.  Note that the third
party would still need to at least pass in an additional user ID
recognizable by our system in order to deal with per-user data (like my
photos or bookmarks or ...).


-- 

 <http://feeds.feedburner.com/aol/SzHO> AbstractioneerJohn Panzer
System Architect
http://abstractioneer.org

"Mike Schinkel" <mikeschinkel@...> wrote:
>
> Benjamin Carlyle wrote: 
> > On the whole the framework doesn't look particularly RESTful 
> > or non-RESTful. It would be up to a particular blueprint and 
> > implementation to conform or not conform to REST principles. 
> > If it is designed for interaction with HTTP and allows 
> > appropriate access to HTTP headers I don't see any obvious 
> > problems on the surface.
> 
> I'm curious; could RESTfulness be more strongly enforced by the
framework?
> 

The first goal for Dream is to make it easier to associate code with
REST concepts.  Currently, we have nice pattern matching on HTTP
methods and URIs, but still lack content-type matching.  Well, 2 out
of 3 is not a bad start.

The unit of communication is messages, which contain a status code,
headers, and a body.  Messages are modeled after HTTP messages,
although they are not tied to any specific implementation, making the
Dream runtime more portable.

Finally, RESTful design is promoted by providing guidelines (such as
REST for the Rest of Us) and examples.  The framework itself permits
developers to implement non-RESTful services, just like an
object-oriented language facilitates non object-oriented code.  The
question of restricting design freedom is a tough one.  It seems that
even the best arguments are met with unusual, but necessary exceptions
to the rules.

My ongoing goal for Dream will be to facilitate tapping in to the
existing richness of HTTP and make it easier for developers to build
applications with it.


Cheers,

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

I think a lot of the things you are objecting to actually are good
rules of thumb that joe-blow-developer can easily understand and
follow. While these rules aren't necessarily constraints imposed by
REST, they aren't in conflict with it either. Most of the article's
content is characterized as "patterns" as opposed to rules or concepts
defined by REST. So the author is being fairly clear about this IMO.

I think this is a really good idea and is much needed. The average
developer would probably appreciate and understand these simple rules
and patterns a lot more easily than an Architectural Style. As long as
the author is clear that these patterns are not defined by REST and
that there are other ways to build RESTful interfaces then I think its
fine.

Many people learn by example, and at this point the bad examples
outnumber the good. We need more good examples.

Andrew Wahbe

--- In rest-discuss@yahoogroups.com, "S. Mike Dierken" <dierken@...>
wrote:
>
> > This introduction will cover some basics of HTTP [...]
> You probably should mention that REST does not mean "HTTP" and
mention why
> you chose to talk about HTTP (like, it display many of the
characteristics
> described by the REST style).
> 
> > Compare this to mounted network drives, whose names have no way of
being
> resolved by a recipient. 
> Huh? I would need an explanation of how that's similar, so this could be
> clarified or replaced with something more understandable.
> 
> > Similarly, we can also query a complex resource, such as a blog,
to get
> parts of the data:
> This isn't querying a resource, it simply /is/ a resource. You might say
> something like a resource can represent complex information like
"all the
> blog comments after a particular timestamp written by 'anonymous' ". The
> client doesn't need to know just how complex things could be for the
server
> - it just does a GET.
> 
> > All data resources support GET, but not all behavioral resources do. 
> What's a "data resource" compared to "behavioral resource" - you might
> rephrase that to say that some resources are read-only.
> 
> > While a GET request cannot have side-effects, it can return only
parts of
> the resource.  
> > This means that GET is both an atomic read, as well as a query
operation.
> This is not correct - GET does not return parts of a resource. At
least, not
> the way you suggest with query terms.
> You might want to describe that a GET could be a simple static file or a
> complex query operation - both are simply retrievals of data.
> 
> > If two PUT operations occur simultaneously, one of them will win and
> determine the final state of the resource. 
> What happens to the other one? I think that both win. REST gives
rise to all
> sorts of win-win situations.
> 
> > In the case of two simultaneous DELETE operations, one of them may
fail
> since the resource 
> > will have already been deleted.
> Nope. It's important to realize that /both/ succeed. There should be no
> error code. The protocol does not assume a "locate object or fail,
activate
> object or fail, invoke method on object" - it just says "make sure the
> resource is gone when the request completes". An absent resource is
just as
> gone as a recently deleted one.
> 
> > The POST operation is very generic and no specific meaning can be
attached
> to it. 
> There is meaning associated with it, and unique aspects regarding
> repeatability and caching.
> 
> > In general, use POST when only a subset of a resource needs to be
modified
> and it cannot be accessed 
> > as its own resource; or when the equivalent of a method call must be
> exposed.
> Rather than suggesting a generic method calls is appropriate via POST,
> perhaps you could narrow it down to modification operations that
don't fit
> into PUT or DELETE.
> 
> > We can also update individual properties of the entry, because
they are
> exposed as nested resources. 
> There isn't a concept of a 'nested resource'. And this example only
works
> because the server implements it that way, it's not part of REST or
HTTP (or
> even most Web server frameworks unfortunately). And there is no
requirement
> that the second resource that is the 'property of the entry' use a
URI with
> paths - it could just as easily be:
>  PUT http://myserver/myaddressbook/johndoe?prop=27
>  PUT http://myserver/myaddressbook/phones?user=johndoe&type=work
> 
> 
> 
> > -----Original Message-----
> > From: rest-discuss@yahoogroups.com 
> > [mailto:rest-discuss@yahoogroups.com] On Behalf Of Steve G. Bjorg
> > Sent: Monday, January 01, 2007 9:28 PM
> > To: rest-discuss@yahoogroups.com
> > Subject: [rest-discuss] Request for feedback: REST for the Rest of Us
> > 
> > I've created a short tutorial on REST and some common 
> > resource/service patterns.  The tutorial is based on my 
> > experience with designing the API for our DekiWiki application [1].
> > 
> > I would welcome feedback on the accuracy of the content.  The 
> > tutorial will be used to introduce developers to REST and 
> > establish a common framework for designing services.
> > http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us
> > 
> > Thanks in advance for taking a look at it.
> > 
> > 
> > Cheers,
> > 
> > - Steve
> > 
> > [1] http://doc.opengarden.org/DekiWiki_API/Reference/DekiWiki
> > 
> > --------------
> > Steve G. Bjorg
> > http://www.mindtouch.com
> > http://www.opengarden.org
> > 
> > 
> > 
> >  
> > Yahoo! Groups Links
> > 
> > 
> >
>

Nic James Ferrier wrote:
> ...
> There's a REST API!
>
>   http://dev.aol.com/aol_video/index.html
>
> Except this isn't REST. It isn't even HTTP for God's sake. It's just
> stupid. There are methods embedded in the URIs. Everything is done
> with GET. 
To more accurately reflect what the API is, the documentation is going 
to be updated to use the more generic "Web APIs" instead of "REST APIs" 
(we had a Meeting). 

I think it would be interesting to see how the non-personalized portions 
of the video search API would be best represented in a RESTful way.  
(This portion doesn't require authentication and contains no modifying 
methods: http://developer.searchvideo.com/RESTAPIDocumentation.php).  
What's missing?  What additional features/documenation would be useful?  
(Caching?)  Should OpenSearch be considered?

(The "User Methods" which require both authentication and do 
modification are more problematic.  But they're clearly not REST so I'm 
not sure it's useful to talk about them on this list in their current 
form.  They actually contain a fair amount of protection against 
accidental or malicious modification, incorporating a hash signature 
which covers the user token and the parameters, and which can't be faked 
without stealing a shared secret.)

-- 
Abstractioneer <http://feeds.feedburner.com/aol/SzHO>John Panzer
System Architect
http://abstractioneer.org

> I think this is a really good idea and is much needed. The 
> average developer would probably appreciate and understand 
> these simple rules and patterns a lot more easily than an 
> Architectural Style. As long as the author is clear that 
> these patterns are not defined by REST and that there are 
> other ways to build RESTful interfaces then I think its fine.
I agree - after I sent my comments I thought that maybe the page wasn't a
tutorial on REST, so much as how that particular framework does things. But
there are portions that are not server framework specific - like the
description of a second DELETE request failing. Describing those correctly
doesn't hurt.

Hi Steve,

I just read the article. It is quite nice, but isn't there one  
problem with it? Statements like:

GET 	/resource 	Retrieve the entire resource.  Query parameters may  
be available to retrieve only parts of the resource.

And:

For example, the following GET operation retrieves the definition of  
the EightBallService (Dream SDK/Tutorials/8-Ball):

GET http://myserver/host/blueprints/ 
MindTouch.Dream.Tutorial.EightBallService

This operation will return the following XML document:

<blueprint>
...
</blueprint>

To obtain the output in JSON, simply add the dream.out.format=jsonp  
query parameter to the URI:

http://myserver/host/blueprints/ 
MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp

({
...
}

My understanding as that URIs in HTTP are opaque, and that each URI  
references a *different* resource. Therefore:

http://myserver/host/blueprints/ 
MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp

Does not retrieve a different format of the resource at:

GET http://myserver/host/blueprints/ 
MindTouch.Dream.Tutorial.EightBallService

It retrieves a different resource. In other words, my understanding  
of the HTTP spec's use of the term "resource," and also Roy's use of  
it in his thesis, gives no special meaning to a question mark in a URI.

I do exactly what you are describing, because the user trying to  
figure out our information architecture from the URIs may indeed  
apply special meaning to that question mark. (In my model for URI  
design, the part of the URI left of the question mark defines a  
conceptual thing from the user's perspective, but not a resource from  
the HTTP or REST perspective.) So I think it makes sense to do what  
you're doing from a usability perspecitve, but my feeling is your  
article may be inaccurate when it says you can apply query parameters  
to a URI to get a subset or different format for a single resource.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Jan 1, 2007, at 9:27 PM, Steve G. Bjorg wrote:

> I've created a short tutorial on REST and some common resource/service
> patterns.  The tutorial is based on my experience with designing the
> API for our DekiWiki application [1].
>
> I would welcome feedback on the accuracy of the content.  The tutorial
> will be used to introduce developers to REST and establish a common
> framework for designing services.
> http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us
>
> Thanks in advance for taking a look at it.
>
>
> Cheers,
>
> - Steve
>
> [1] http://doc.opengarden.org/DekiWiki_API/Reference/DekiWiki
>
> --------------
> Steve G. Bjorg
> http://www.mindtouch.com
> http://www.opengarden.org
>
>
>
>
> Yahoo! Groups Links
>
>
>
>

Mike,

Sorry, I think I misunderstood you.  I think we're in agreement that 
both the end user and the intermediary's identities need to be verified 
to some degree, and the existing APIs do that.  The issue of how the 
user controls the authorization of the intermediary to perform services 
on behalf of them is complicated.  I'm honestly not sure what the video 
search API does in all the cases but there are other APIs where the user 
can control the settings (and choose to "remember this choice in the 
future") explicitly and in a fine-grained way.  My main point was that 
this is a contributing reason why the authentication steps go through a 
web page presented at least theoretically directly to the user, rather 
than being purely protocol-based.

-John

S. Mike Dierken wrote:
> I don't understand how this gives control to third parties.
> What I read here 
> http://developer.searchvideo.com/RESTAPIAuthSpec.php indicated that 
> both and application-id and 'shared secret' are provided by AOL. It 
> appears that requests must provide a 'signature' which is based in 
> part on that shared secret - the AOL service must also know this 
> shared secret to authenticate that signature, so it seems that 
> authentication is performed by the AOL service.
> The current approach involves the end user to provide authorization 
> every 60 minutes through the process of displaying the appropriate web 
> pages hosted by AOL - by not providing their username/password the 
> user essentially does not authorize access. I was just suggesting that 
> this authorization be more explicit and the end-user could even see a 
> list of applications and whether they are authorized or not.
>  
> > Note that the third party would still need to at least pass in an 
> additional user ID recognizable by our system
> > in order to deal with per-user data (like my photos or bookmarks or ...).
> Yes - that is desired. Some of the documented APIs call this a token:
>  http://api.searchvideo.com/apiv3
>        ?method=truveo.users.getFavoriteVideos
>        &appid=MY_APPID
> *       &token=USER_TOKEN*
>        &start=0
>        &results=10
>        &showRelatedItems=1
>        &sig=[signature]

Bill Venners <bv-svp@...> wrote:
> My understanding as that URIs in HTTP are opaque, and that each URI  
> references a *different* resource. Therefore:
> 
> http://myserver/host/blueprints/ 
> MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp
> 
> Does not retrieve a different format of the resource at:
> 
> GET http://myserver/host/blueprints/ 
> MindTouch.Dream.Tutorial.EightBallService
> 
> It retrieves a different resource. In other words, my understanding  
> of the HTTP spec's use of the term "resource," and also Roy's use of  
> it in his thesis, gives no special meaning to a question mark in a URI.
> 
> I do exactly what you are describing, because the user trying to  
> figure out our information architecture from the URIs may indeed  
> apply special meaning to that question mark. (In my model for URI  
> design, the part of the URI left of the question mark defines a  
> conceptual thing from the user's perspective, but not a resource from  
> the HTTP or REST perspective.) So I think it makes sense to do what  
> you're doing from a usability perspective, but my feeling is your  
> article may be inaccurate when it says you can apply query parameters  
> to a URI to get a subset or different format for a single resource.

I'm not sure I'm following your point.  Are you saying I could express
it better without using the term 'resource'?  But what should it be
called then?

Let's look at the following use case (for Dream):
1) we have a URI that points to an XML document (e.g.
http://server/recipes)
2) doing a GET on this URI gives us the document verbatim
3) doing a GET?dream.out.format=jsonp gives us the document in a
different representation (sending 'Accept: application/json,
text/javascript' should trigger the same conversion)
4) doing a GET?dream.out.select=/list/entry[author='Julia Child']
gives us the XML sub-document that matches the xpath expression

I would say that #2-#4 all refer to the same "resource", but chose to
represent it in different ways.

If I understood you correctly, you are stating the
"http://server/recipes" and
"http://server/recipies?dream.out.format=jsonp" identify two different
resources, because they are different URIs.  Is that correct?  And if
yes, is there a less strict interpretation that would weaken this
equality relationship to only apply to the scheme, authority, and path
components of the URI (i.e. excluding user name, password, path
parameters, query parameters, and fragment)?  I think such an equality
relationship would be useful and feel intuitive.  And would certainly
be deserving of a name by which it could be referred to.


- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Hi Steve,

On Jan 3, 2007, at 2:23 PM, Steve G. Bjorg wrote:

> Bill Venners <bv-svp@...> wrote:
>> My understanding as that URIs in HTTP are opaque, and that each URI
>> references a *different* resource. Therefore:
>>
>> http://myserver/host/blueprints/
>> MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp
>>
>> Does not retrieve a different format of the resource at:
>>
>> GET http://myserver/host/blueprints/
>> MindTouch.Dream.Tutorial.EightBallService
>>
>> It retrieves a different resource. In other words, my understanding
>> of the HTTP spec's use of the term "resource," and also Roy's use of
>> it in his thesis, gives no special meaning to a question mark in a  
>> URI.
>>
>> I do exactly what you are describing, because the user trying to
>> figure out our information architecture from the URIs may indeed
>> apply special meaning to that question mark. (In my model for URI
>> design, the part of the URI left of the question mark defines a
>> conceptual thing from the user's perspective, but not a resource from
>> the HTTP or REST perspective.) So I think it makes sense to do what
>> you're doing from a usability perspective, but my feeling is your
>> article may be inaccurate when it says you can apply query parameters
>> to a URI to get a subset or different format for a single resource.
>
> I'm not sure I'm following your point.  Are you saying I could express
> it better without using the term 'resource'?  But what should it be
> called then?

Yes, since you're attempting to explain REST, and the term "resource"  
I think means in REST what it means in HTTP, which is very specific.  
I CC'd the list because I wasn't 100% sure of that, so see if anyone  
has a different definition of "resource" in the HTTP and/or REST  
context.

> Let's look at the following use case (for Dream):
> 1) we have a URI that points to an XML document (e.g.
> http://server/recipes)
> 2) doing a GET on this URI gives us the document verbatim
> 3) doing a GET?dream.out.format=jsonp gives us the document in a
> different representation (sending 'Accept: application/json,
> text/javascript' should trigger the same conversion)
> 4) doing a GET?dream.out.select=/list/entry[author='Julia Child']
> gives us the XML sub-document that matches the xpath expression
>
> I would say that #2-#4 all refer to the same "resource", but chose to
> represent it in different ways.
>
> If I understood you correctly, you are stating the
> "http://server/recipes" and
> "http://server/recipies?dream.out.format=jsonp" identify two different
> resources, because they are different URIs.  Is that correct?  And if
> yes, is there a less strict interpretation that would weaken this
> equality relationship to only apply to the scheme, authority, and path
> components of the URI (i.e. excluding user name, password, path
> parameters, query parameters, and fragment)?  I think such an equality
> relationship would be useful and feel intuitive.  And would certainly
> be deserving of a name by which it could be referred to.
>
I agree. Our URIs in our new architecture do a similar thing. But I  
don't call them "resources." I call them whatever they are: article,  
forum post, etc. I also do the "container" pattern a lot as you named  
it. You could call these things (for lack of a better word) resources  
if you want, but it seems like overloading the term in an article  
trying to explain REST. You might try coming up with a better name  
than "thing" that isn't "resource."

On the other hand, I'm not really sure it's an article about REST if  
you're going in that direction. It may be more an article about user- 
friendly web information architecture and URI design. At least that's  
how I think of those patterns you described, that the URI to the left  
of the question mark defines one "thing" in the *user's* mental model  
of your website. The stuff to the right of the question mark the user  
can think of as stuff that customizes their view of the "thing." But  
those different URIs giving views of the same "thing" are not  
representations of resources in the HTTP terminology, which is where  
I believe REST lives. In that worldview each different URI is a  
different "resource" that may have multiple "representations."

For example:

http://www.artima.com/articles

Is a view of the collection of articles that shows the most recently  
published 15 articles.

http://www.artima.com/articles?p=7

Shows page seven of the same list, the collection of articles shown  
in most-recently-published order. Here the "thing" in the user's mind  
is the collection of articles. But from the HTTP perspective, from my  
reading of the spec, these are two distinct resources each of which  
could have multiple representations, not two representations of the  
same resource.

Anyway, my feefback is simply to be very clear on the terms in your  
article, and since it is an article attempting to explain REST, try  
to use "resource" and "representation" as it is used in the HTTP spec  
and Roy's paper. (And I welcome clarification from others if I'm not  
understanding these terms correctly.)

Bill

>
> - Steve
>
> --------------
> Steve G. Bjorg
> http://www.mindtouch.com
> http://www.opengarden.org
>
>
>
>
> Yahoo! Groups Links
>
>
>
>

S. Mike Dierken wrote:
> > I think this is a really good idea and is much needed. The 
> > average developer would probably appreciate and understand 
> > these simple rules and patterns a lot more easily than an 
> > Architectural Style. As long as the author is clear that 
> > these patterns are not defined by REST and that there are 
> > other ways to build RESTful interfaces then I think its fine.
> I agree - after I sent my comments I thought that maybe the page
wasn't a
> tutorial on REST, so much as how that particular framework does
things. But
> there are portions that are not server framework specific - like the
> description of a second DELETE request failing. Describing those
correctly
> doesn't hurt.

So DELETE just indicates the intent to transition to a deleted state.
 Thus applying DELETE to a deleted resource is successful because the
outcome is a deleted resource.  Correct?  

Just to make sure, is that the generally accepted interpretation?

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Bill Venners wrote:

> My understanding as that URIs in HTTP are opaque, and that each URI
> references a *different* resource. Therefore:
> 
> http://myserver/host/blueprints/ <http://myserver/host/blueprints/>
> MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp
> 
> Does not retrieve a different format of the resource at:
> 
> GET http://myserver/host/blueprints/ <http://myserver/host/blueprints/>
> MindTouch.Dream.Tutorial.EightBallService
> 
> It retrieves a different resource. 

Bill, the same resource is the accessed in both cases as the resource 
identifier is the same - namely the pieces up to the query string (see 
para two in 3.2.2 of the HTTP spec). The only criticism I'd have of the 
URL design here is that "dream.out.format" is long to type.

cheers
Bill

Bill de hOra wrote:
> Bill, the same resource is the accessed in both cases as the resource 
> identifier is the same - namely the pieces up to the query string (see 
> para two in 3.2.2 of the HTTP spec). 

Wonderful!  All is good then.


> The only criticism I'd have of the 
> URL design here is that "dream.out.format" is long to type.

I got the idea to use namespaces on query parameters from OpenID.  I
think it's a great idea.  Using something like 'output' is just
calling for trouble.  At some point someone will want to use a query
parameter that is already used by the framework and then the mess
begins.  'dream.format' couldn't be used either, because the framework
also supports an inbound data transform (so you can post/put JSON from
the browser).

That said, the next version of Dream (Denim) will probably use HTTP
headers instead.  So that 'Content-Type: text/javascript' gets
converted to 'Content-Type: application/xml' when appropriate and
conversely with 'Accept: text/javascript' the content will be
transformed to the target representation.  This way, there is no need
to play with URI query parameters and it also leverages nicely the
capabilities that already exist in the protocol.  However,
'dream.out.format' makes for a nicer better demo in the browser! :)

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

On Jan 3, 2007, at 4:22 PM, Steve G. Bjorg wrote:
> Bill de hOra wrote:
> > Bill, the same resource is the accessed in both cases as the  
> resource
> > identifier is the same - namely the pieces up to the query string  
> (see
> > para two in 3.2.2 of the HTTP spec).
>
> Wonderful! All is good then.

That was the case back in 1994, when I wrote it.  It has not been true
for a long time since.  It is one of those things that became untrue
once people realized that the interface had no reason to respect such
a distinction (and rightly so -- it introduces coupling where none is
needed) and so the distinction was removed server-side to reflect the
migration of resources to new implementations.

The resource in HTTP is the mapping from the entire identifier
(including scheme, authority, path, and query) to a set of values.
For two resources to be the same, they must map to the same set
of values for all time.  There is no way to determine that by
inspecting the identifiers, aside from scheme-defined equivalence.

....Roy

Hi Bill,

On Jan 3, 2007, at 3:26 PM, Bill de hOra wrote:

> Bill Venners wrote:
>
>> My understanding as that URIs in HTTP are opaque, and that each URI
>> references a *different* resource. Therefore:
>>
>> http://myserver/host/blueprints/ <http://myserver/host/blueprints/>
>> MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp
>>
>> Does not retrieve a different format of the resource at:
>>
>> GET http://myserver/host/blueprints/ <http://myserver/host/ 
>> blueprints/>
>> MindTouch.Dream.Tutorial.EightBallService
>>
>> It retrieves a different resource.
>
> Bill, the same resource is the accessed in both cases as the resource
> identifier is the same - namely the pieces up to the query string (see
> para two in 3.2.2 of the HTTP spec). The only criticism I'd have of  
> the
> URL design here is that "dream.out.format" is long to type.
>
Thanks very much for that pointer. You're right about 3.2.2, and that  
challenges my understanding of HTTP terminology. So whether I GET:

http://www.artima.com/articles

or

http://www.artima.com/articles?p=7

I get back a representation of the *same* resource (which from the  
user's perspective is a collection of articles). Is it correct to  
call these different "representations" of the same resource? It says  
in the spec that a representation is "An entity included with a  
response that is subject to content negotiation, as described in  
section 12. There may exist multiple representations associated with  
a particular response status." Tacking on a "?p=7" is not content  
negotiation as defined by the spec. So I think all I can say is I get  
back *a* representation of the same "collection of articles" resource  
from any URI that is "http://www.artima.com/articles" to the left of  
the question mark.

I looked again at 3.11 in the spec, and I see they left sufficient  
wiggle room for entity tags and caching. Given that the spec says  
entity tags are per-resources, my understanding to date had been that  
I could have a unique set of entity tags per URI. But since the above  
two distinct URIs really refer to the same resource, their entity  
tags should really taken from the same set. But the spec says that "A  
given entity tag value MAY be used for entities obtained by requests  
on different URIs. The use of the same entity tag value in  
conjunction with entities obtained by requests on different URIs does  
not imply the equivalence of those entities." This says a cache can  
only rely on identical entity tags meaning the entity is identical if  
it is from the same URI. So in practice it worked like I had  
imagined: I can have a unique set of entity tags per URI, and If-None- 
Match requests from caches will really work per-URI, not per-resource.

Does that sound correct?

Bill

> cheers
> Bill
>
>
>
> Yahoo! Groups Links
>
>
>
>

Roy T. Fielding wrote:
> 
> The resource in HTTP is the mapping from the entire identifier
> (including scheme, authority, path, and query) to a set of values.

I'm reluctant to quibble with an editor, but I was referring to the 
means of identification as laid out, and not the substance of the resource.

cheers
Bill

On Jan 3, 2007, at 5:13 PM, Bill de hOra wrote:
> Roy T. Fielding wrote:
> >
> > The resource in HTTP is the mapping from the entire identifier
> > (including scheme, authority, path, and query) to a set of values.
>
> I'm reluctant to quibble with an editor, but I was referring to the
> means of identification as laid out, and not the substance of the  
> resource.

What is the difference?   ;-)

....Roy

Benjamin,

----------------------
Objection: "Clients can't be programmed to complete forms"

Counter-example: This machine automatically fills out a form based on
a vocabulary every day: Your web browser, when it pre-fills form
fields for you. Browsers know that user name and password fields on
HTML forms usually have consistent names. And Google Toolbar saves
some common personal info about you and auto-populates your name,
address, etc, based on a common vocabulary. You just program a client
to map information it has, to fields identified by name -- a
vocabulary.


----------------------
Misconception: "Forms are schemas"

Correction: Forms are  queries made by the server to the client. "Give
me the data you have named 'author-email".  Schemas describe relations
among objects. They describe models, not messages.


----------------------

Starry-eyed delusion: A Standards process can capture the union of all
the semantics any server could manifest.
Corollary: Exchanging these documents is "scalable"

Real world experience: RosettaNet PIP 3A4. Thoroughly specified
schemas describing almost every possible Purchase Order Request and
Response. Guess how long it takes one large computer manufacturer to
shake out enough impedance mismatches to get going with each new
trading partner? 30-60 days, and that is a dedicated team of experts
exchanging test messages, "validating" them, discovering and resolving
the semantic mismatches in even the "valid" documents. So that's one
or two months per partner. How long does it take to ramp on just 100
partners? Years. Not  web scale, is it?

Exchanging pre-defined special purpose documents, as APP does,
satisfies REST's definition, but it's not webby.  Forms have proven
their scalability on the web, because they promote loose coupling.
They offer hope that web services could be deployed at web scale.

Hugh


On 1/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> On Tue, 2007-01-02 at 12:31 -0600, Hugh Winkler wrote:
> > On 12/31/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > > On Sat, 2006-12-30 at 19:08 -0600, Hugh Winkler wrote:
> > > > On 12/30/06, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > > > > I'm not sure who you think will interpret this form on the client
> > > > side.
> > > > > You see, the thing is that the atom document format is already a
> > > > form. A
> > > > > client has already received the form by being programmed in a
> > > > particular
> > > > > way, and is now submitting the form. It knows what information
> > > > should be
> > > > > placed in each of the named fields. It knows how to construct the
> > > > end
> > > > > document.
> > > > Ah, but it is a standard form for all servers -- not for my particular
> > > > server app. And to know what kind of form to submit, you read a spec
> > > > -- you did not GET the description from the server. It's all baked in
> > > > at design time.
> > > Exactly. It has been agreed ahead of time.
> > That's the problem --- "ahead of time" rather than dynamically at run time.
>
> What you have to understand here, is that you are trying to replace
> human agreement with machine agreement. Humans are good at negotiating
> standards like atom. It's a hard problem, but standards get nailed out.
> Information producers agree to transform their internal models into the
> standard format. Information consumers agree that the standard format is
> a suitable source of data for their internal models. Internal models
> often have to bend as part of this process, and eventually realign
> around a competent standard to be more simliar than they are different.
>
> Machines are not good at negotiation. You give a machine a form to fill
> out, and the machine already needs to know how to fill out the form
> before it starts. The form says "title", "summary", "content". The
> machine already needs an internal model that has those elements. The
> form says "don't give me the summary", the client could have code
> written to say "only send the subset of the standard which the server
> says it can accept". That's as good as you can do.
>
> You can't give a client an arbitrary form that isn't a simple subset and
> expect it to know what to do. If the client software wasn't written to
> know that only one author might be supported on the other side, it can't
> choose which author it should supply any better than the server side.
> You are lucky if it can interpret the server's instructions not to
> supply more than one at all.
>
> You can't arbitrarily place restrictions on the client as to how it
> should fill out its content. The only practical way to do it is to write
> a program that the client must run over a standard atom data model in
> order to fit the server's point of view. And guess what: That's the same
> program you would run on the server side if the client just submitted
> the atom document in the first place.
>
> Clients can't deal with unexpected server demands. Server demands are
> only expected if they are negotiated between humans, which is to say
> they are part of the atom specification. You can't do any better than
> what is in the standard by supplying a form.
>
> > >Now, I can just send my POST
> > > request and know that the server understands a useful subset of what I
> > > am sending them.
> > Not sure how you would know it understands a useful subset. You won't
> > have the slightest idea what parts of your document it understands, or
> > doesn't. doesn't handle multiple authors? Can only accept text/plain
> > for <title>?
>
> I know it understands because we agreed on the content through the atom
> standardisation process. We agreed that I would send this much and the
> server would understand that much. Whether understand means "completely
> model" is up to the server. It is free to cut the xhtml out of its
> title. It is even free to use the xhtml content as text/plain. That's
> its perrogative. What is not in its perrogative is to reject a
> well-formed and valid atom document. If it intends to do that it should
> not claim to understand atom in the first place.
>
> > > What you are suggesting is that I first need to obtain a schema document
> > > (which you are calling a form)
> > A schema document is not a form. Maybe we should stay away from XML
> > for a moment. Think HTML form...  which is a little "program" telling
> > the UA how to serialize a submission.
>
> You are describing the set of valid documents I can submit to you. You
> can call it a form if you like, but it is more correctly a schema.
>
> If you are no longer talking about a schema, and are now talking about a
> program to transform my atom content into your sub-atom content... then
> why aren't you running that program on the server side?
>
> > > to see if the server is actually
> > > understanding only a subset of the atom vocabulary.
> > Not a subset... could be a superset.
>
> Now you are talking about the client supplying more elements than it
> knows how to supply. You are presumably talking about extensions to the
> standard, but extensions are standards too. Extensions require human
> agreement between client and server in order to be understood.
>
> > > Then I need to
> > > customize my content to conform to this subset. As a machine, I don't
> > > have any good way of doing that.
> > See, you have this problem anyway. If you are sending a server stuff
> > it doesn't understand, or not enough stuff, your application will
> > fail.
>
> But I have already agreed through the standardisation process with the
> server that it will understand my content. My application will only fail
> if the server fails to implement the specification.
>
> > With forms, at least, your application knows "Hey, I don't know how to
> > fill out this required field". Same as a human would using an HTML
> > form. Your client can report that to a human for correction.
>
> It only knows if I write code. I only write code if I have communicated
> with the guy who wrote the server about what is permissible. I have
> already done this. We called that conversation the atom standardisation
> process.
>
> Why do you think a human in the loop can do anything about the failure
> to communicate? Are they going to hack on their client application every
> time a server says it only understands an unexpectedly-small subset of
> atom or demands an extension element be supplied? No... if there is a
> human in the loop she will write an email to the server's administrator
> to inform him of his bug in failing to implement the specification. It
> is not the client's problem. It is the server's problem.
>
> > Atom (and any application protocol based on exchanging known document
> > types) has to trade off between exhaustively specifying application
> > behavior and exhaustively specifying failure handling.
>
> And exhaustively supporting forwards-compatability for extensions, and
> exhaustively trading server and client-side complexity for protocol
> features.
>
> > >If I come up to a server that has
> > > support for an unexpectedly small subset of atom, I then have to
> > > customize my content in an unexpected way.
> > It is better for you to do the customizing. TTake the example of a
> > server that simply cannot honor text/html or application/xhtml+xml in
> > the title field. It can only handle text/plain. Atom protocol says
> > nothing at the moment about this situation, except that the server can
> > change your POSted data as it needs to. So presently my server either
> > a) rejects your submission or b) stores it as text/plain.  Better
> > would be for your client to receive an Xform with a constraint
> > specifiying "text/plain" only -- then, if the user had any imprtant
> > rich content they wanted to put in the title, they can at least try to
> > compensate.
>
> No no no.... the client doesn't know how to customise the content. As
> the author of the client I relied on the atom specification that says I
> can supply a content element and I did. Now your server is telling me it
> doesn't understand it and wants a summary element instead? My client is
> not written to deal with that. The server can deal with its own
> shortcomings, thankyou. If it doesn't understand the protocol it should
> stop speaking it.
>
> If the server doesn't understand xhtml in the title, then tough! It
> knows that it must be expected to deal with xhtml in the title because
> we agreed through the standardisation process that it should be capable.
> How it provides that support as the atom spec rightly points out is up
> to the server. Maybe it will strip out anything in angle-brackets before
> storing the value into its internal title variable. Maybe it will just
> use the xhtml content verbatim. That's the server's problem. It isn't
> permitted to reject my submission. How is my client supposed to know
> that what it needs to do in the face of this dumb server? We already
> agreed that xhtml was fine, and now this server wants to go back on
> that? Move complexity to me, will you? No thanks. I'll find another
> server to talk to. Maybe one that understands xhtml in the title.
>
> > >That is to say, I way that
> > > noone programmed me to customise my content in :)
> > Well, you would have programmed it from this pov, so you would have
> > handled these exceptional situations.
>
> I don't write client software to deal with broken servers that don't
> implment the spec. It is up to the server to deal with the problem if it
> can't translate my request precisely.
>
> > > The server, on the other hand, is in a good position to customise the
> > > content. It knows which subset of atom it understands, and it knows what
> > > atom is generally. It knows multiple authors might be required, so is in
> > > a position to either model those multiple authors or use an algorithm to
> > > select an author for its model from the available list.
> > See above. Yes, you are describing the undesirable behavior the
> > current APP forces you into.
>
> Quite the opposite. Your suggestion doesn't hold water. The spec
> reflects decades of experience in developing protocols that work and can
> evolve succesfully for decades to come. Do you think you can do better
> without having written software on more than one side of the
> client/server fence?
>
> > > > What I proposed is that the form delivered by a server have just the
> > > > elements that make sense for the server. My server might not know what
> > > > to do with a <source> element. Using the standard "form", my server
> > > > has to have handling in place if you submit a <source> element, and it
> > > > has to describe to you the problem if you do submit <source> and my
> > > > server rejects it.
> > > All atom elements make sense to the server, even if they don't fit the
> > > server's internal model.
> > > The server implements atom, after all.
> > not so -- the client may submit extgension elements the server isn't aware of.
>
> And the server is required to ignore them and the client is required to
> accept that old servers will ignore them. That's the way extensible
> protocols work. If the extension is good it will be supported. If it is
> not it will be ignored, sidelined, and eventually forgotten.
>
> > > What you
> > > are suggesting is adding an extra message exchange to move the
> > > complexity of fitting atom into the server's model back to the client.
> > > Neither side is going to be great at solving a model mismatch problem,
> > > but the client is likely to be downright incapable.
> > As above: The client is in the best position to take corrective
> > action, so as to best fulfill its intent.
>
> Show me the code. Your solution requires me to write client-side code
> every time a new kind of dumb server is placed on the internet. That
> doesn't work. That doesn't scale. Machines can't negotiate, only humans
> can... and we already have. If you have anything more to add to that
> conversation you had better to do it. Don't try to hold a separate
> conversation with my client software. It doesn't know how to hold that
> conversation.
>
> > Forms made the web adaptive. Go to any airline reservation web site.
> > They're all the same, but different too. They mostly do the same
> > things, but Orbitz offers packages with hotels and cars, while Delta
> > offers connections with partner airlines, and  Priceline won't let you
> > see the itinerary. There's some shared vocabulary among all those
> > sites but varying behavior. If the airlines standardize their
> > vocabulary for forms, you could program a client to interact,
> > adaptively, with all those sites. But you could not constrain
> > Priceline's app to squeeze into the same behavior model as Delta's.
> > And you shouldn't -- you should encourage diversity among web apps, as
> > has been successful on the web to date.
>
> The evolvability of HTML and HTTP are what have been successful on the
> web to date. Atom follows the evolvability and agreement model of its
> predecessors. Do you really want your web server to have to retrieve a
> form from every browser that requests a html page before it can be
> returned? When that form says "I don't understand paragraph markers",
> what will your web server do to make the content fit?
>
> Benjamin.
>
>

> 
> That said, the next version of Dream (Denim) will probably 
> use HTTP headers instead.  So that 'Content-Type: 
> text/javascript' gets converted to 'Content-Type: 
> application/xml' when appropriate and conversely with 
> 'Accept: text/javascript' the content will be transformed to 
> the target representation.  This way, there is no need to 
> play with URI query parameters and it also leverages nicely 
> the capabilities that already exist in the protocol.  
> However, 'dream.out.format' makes for a nicer better demo in 
> the browser! :)
> 
I once built a framework like this and used the names from HTTP with a
prefix, like "?do:accept=text/xml"
That way I could point to an existing definition of what 'accept' means as
well as the allowed values. With "dream.out.format" it's not clear that a
MIME type is to be supplied.

On 1/2/07, Mike Schinkel <mikeschinkel@...> wrote:
> Walden Mathews wrote:
>  > Maintaining multiple URIs for the same resource is not
>  > best practice. For the same reason you want uniformity in
>  > methods, you want one preferred URI for identifying a
>  > resource. The server should redirect requests for other
>  > equivalent URIs to the preferred one. Althought that's not
>  > quite what you are asking, I think it is the answer.
>
>  I'm curious why you make the above statement. Is there a W3C finding that documents this, or some other paper?  I've been doing a significant amount of research on URLs and URI best practices in the past 3+ months and have found nothing like this (though I could have missed it.)

http://www.w3.org/TR/webarch/#avoid-uri-aliases

  "URI owner SHOULD NOT associate arbitrarily different URIs with the
same resource."

   -joe

-- 
Joe Gregorio        http://bitworking.org

Joe Gregorio wrote:
> >  I'm curious why you make the above statement. Is there a 
> W3C finding 
> > that documents this, or some other paper?  I've been doing a 
> > significant amount of research on URLs and URI best 
> practices in the 
> > past 3+ months and have found nothing like this (though I 
> could have 
> > missed it.)
> 
> http://www.w3.org/TR/webarch/#avoid-uri-aliases
> 
>   "URI owner SHOULD NOT associate arbitrarily different URIs 
> with the same resource."

Thanks for the link.  

*Sigh*  I think that finding optimizes one aspect of the web at the expense
of others. It certainly places limits on what can be done from a URL
usability perspective.  While I do understand the rationale behind it, I
plan to advocate that the finding needs be reconsidered in the future.
However I know that the current state of web specifications makes that
impractical, I want to look at root cause of why it's not practical and see
what we can do to address it. The research I'm doing has been heading me
down this path and I will be writing about it at length in the near future.

BTW, I'd argue that a worst problem exists with respect to URL aliases from
the perspective of web apps being sloppy. Web apps that use query parameters
in different orders, that use sessionIDs and userID as query parameters
where it doesn't change the content, and so on create lots of URI aliases
unintentionally. Ironically, nobody says much about that. That's another
problem that I also think really should be addressed at the same time.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Roy T. Fielding wrote:
> The resource in HTTP is the mapping from the entire identifier
> (including scheme, authority, path, and query) to a set of values.
> For two resources to be the same, they must map to the same set
> of values for all time. There is no way to determine that by
> inspecting the identifiers, aside from scheme-defined equivalence.
 
I think I get what you are saying, but I want to be sure. Basically you are
saying that each of the following URLs point to a DIFFERENT resource as far
as REST is concerned, correct:

http://www.foo.com/bar
http://www.foo.com/bar/  
http://www.foo.com/bar/index.php  
http://www.foo.com/bar?a=1&b=2
http://www.foo.com/bar?b=2&a=1
http://www.foo.com/bar/?a=1&b=2
http://www.foo.com/bar/?b=2&a=1
http://www.foo.com/bar/index.php?a=1&b=2 
http://www.foo.com/bar/index.php?b=2&a=1

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Bill, Scott,

yepp, APP solves all of these in a standardized way.

IIRC there is actually already a 'standardized' means to find the  
editing-resource of another resource by pure HTTP mechanisms: The  
Link header together with the 'source' relation. That is, if the  
server tells you about a related resource via a Link of type 'source'  
all editing should be applied to that one.

I recall Roy having mentioned that on one of the Atom lists.

Though I have no idea about the actual standardization status of  
either the Link header nor the source relation...

Jan



On 08.08.2006, at 18:11, Bill de h�ra wrote:

> Scott Chapman wrote:
> >
> >
> > If hitting a URL with GET is supposed to give you a view of the  
> resource
> > and
> > it's not a form by default, then how to do you get a <form...>  
> view of
> > it for
> > editing?
> >
> > The same applies to getting a blank form for creating a new  
> resource.
> >
> > How are people handling these situations in their RESTful designs?
>
> The most common pattern today is to provide the form at another URL,
> which you typically embed as a link in the representation. Blog  
> APIs do
> something similar by providing a URL you post into. Looking further  
> out,
> atom protocol will standardize a means for getting at what it calls  
> the
> "edit-uri" for a resource.
>
> It's a good question, illuminating even.
>
> cheers
> Bill
>
>
> 

[ Attachment content not displayed ]

On 1/3/07, Hugh Winkler <hughw@...> wrote:
>  Starry-eyed delusion: A Standards process can capture the union of all
>  the semantics any server could manifest.
>  Corollary: Exchanging these documents is "scalable"
>
>  Real world experience: RosettaNet PIP 3A4. Thoroughly specified
>  schemas describing almost every possible Purchase Order Request and
>  Response. Guess how long it takes one large computer manufacturer to
>  shake out enough impedance mismatches to get going with each new
>  trading partner? 30-60 days, and that is a dedicated team of experts
>  exchanging test messages, "validating" them, discovering and resolving
>  the semantic mismatches in even the "valid" documents. So that's one
>  or two months per partner. How long does it take to ramp on just 100
>  partners? Years. Not  web scale, is it?

That fits with my experience.  Previous ecommerce standards, ANSI X12
EDI and EDIFACT, were even worse: took months.

Some of the same people have now created UBL: a 4th or 5th generation
(X12, EDIFACT, RosettaNet, UBL, depending on whether you put ebXML
into that geneology).  We'll see how quickly new trading partners can
get going using that.  I think it's less prescriptive than RosettaNet,
which tried to achieve minimal configuration.

On Wed, 2007-01-03 at 22:23 +0000, Steve G. Bjorg wrote:
> Let's look at the following use case (for Dream):
> 1) we have a URI that points to an XML document (e.g.
> http://server/recipes)
> 2) doing a GET on this URI gives us the document verbatim
> 3) doing a GET?dream.out.format=jsonp gives us the document in a
> different representation (sending 'Accept: application/json,
> text/javascript' should trigger the same conversion)
> 4) doing a GET?dream.out.select=/list/entry[author='Julia Child']
> gives us the XML sub-document that matches the xpath expression
> 
> I would say that #2-#4 all refer to the same "resource", but chose to
> represent it in different ways.

Here is the vocabulary I use:

#2-#4 all refer to different _resources_ becuase they have diffent uris.
>From the client perspective no relationship can be drawn between these
resources without additional information, ie some sort of hyperlink. It
is perhaps peculiar that resources don't always exist within the server.
Sometimes they are implemented as objects in their own right, but other
times a single object might offer many resources or vice versa.
Resources themselves exist between clients and servers as a shared
interface concept.

These different resources all _demarcate_ related _application state_ on
the server side. Each resource selects a piece of state (ie information)
in the server that might be part of a single object, might be a whole
object, or might be parts of several different objects. If we were
talking about databases a resource might demarcate a subset of rows
across multiple tables.

When we GET a resource, we retrieve a _representation_ of that resource.
This representation is a document that contains the information
demarcated by the resource. The same resource might choose to return its
state in several formats, providing several different representations of
its state. Different representations may offer different levels of
semantic fidelity. For example, atom data could be returned in a simple
csv or text file... but then the information couldn't be used in a news
reader client application.

Benjamin.

On Wed, 2007-01-03 at 20:06 -0600, Hugh Winkler wrote:
> Objection: "Clients can't be programmed to complete forms"
> Counter-example: This machine automatically fills out a form based on
> a vocabulary every day: Your web browser, when it pre-fills form
> fields for you. Browsers know that user name and password fields on
> HTML forms usually have consistent names. And Google Toolbar saves
> some common personal info about you and auto-populates your name,
> address, etc, based on a common vocabulary. You just program a client
> to map information it has, to fields identified by name -- a
> vocabulary.
> Misconception: "Forms are schemas"
> Correction: Forms are  queries made by the server to the client. "Give
> me the data you have named 'author-email".  Schemas describe relations
> among objects. They describe models, not messages.

The actual query made by the server to the client is:
Put a text box next to the human-readble text "Please enter your email
address". Return what the user enters into that box as the
"author-email" element of an xml document. Oh, and by the way. Don't
submit it back until that xml document maches this xml schema I supply.

The kind of client atompub is designed to support already has a text
box. It's called "author". Now your form says "give me author-email"...
but there is no author-email box in the application. The application has
already been written and its data model doesn't match yours. Now what
would you like the client to do about it?

If you just want to supply a form to a user, you can do that. You don't
need atompub for that. You don't need any standardisation past HTML
forms or XForms. Atompub is what you are looking for when you want to
write a clever and easy to use thick-client atom authoring client.
Supplying a form to this thick client isn't going to help. You say you
want an author-email box next to the "Please enter your email address"
text? Hey! my interface has already been designed. Where do you expect
me to put that text box? If you want to design your own interface, just
supply the form to a web browser and be done with it. For me, I have my
own user interface. The purpose of atompub is to allow that client with
its complete user interface to submit articles to a server that has also
been written.

> Starry-eyed delusion: A Standards process can capture the union of all
> the semantics any server could manifest.
> Corollary: Exchanging these documents is "scalable"
> 
> Real world experience: RosettaNet PIP 3A4. Thoroughly specified
> schemas describing almost every possible Purchase Order Request and
> Response. Guess how long it takes one large computer manufacturer to
> shake out enough impedance mismatches to get going with each new
> trading partner? 30-60 days, and that is a dedicated team of experts
> exchanging test messages, "validating" them, discovering and resolving
> the semantic mismatches in even the "valid" documents. So that's one
> or two months per partner. How long does it take to ramp on just 100
> partners? Years. Not  web scale, is it?

Bad standards exist, therefore standards are bad. Nice logic. Next I'm
sure you'll tell me about how bad HTML is and why it will never be
deployed or understood by anyone. We should require that web browsers
provide a form for the server to fill out that informs the server of the
client's capabilities. That will help. When the client says it doesn't
understand <h3>, the server will know exactly what to do. It'll just
translate those h3 elements into h2 elements. Of course the programmer
who wrote the server will have anticipated this and written the
capability into it.

Of course the first round of standardisation is a shambles. It hardly
ever works until the authors of clients and servers have some
implementation experience and have developed some mutual trust in their
mutual interests. That is why standards like atom have defined
mechanisms for evolvability, and why atom has been so long in
development despite person-decades of experience in related precursor
standards.

Document standards represent a conversation between document producers
and consumers about their needs. It is a compromise between features and
complexity in problem domains that are rarely mapped out well enough to
have a sane conversation about. Trying to carry on a conversation
outside of the process however between your server and my client isn't
going to get anywhere. Machines can't communicate unless their
programmers already can. Unless the author of the client software and
the author of the server software agree out of band, communication
cannot happen.

> Exchanging pre-defined special purpose documents, as APP does,
> satisfies REST's definition, but it's not webby.  Forms have proven
> their scalability on the web, because they promote loose coupling.
> They offer hope that web services could be deployed at web scale.

What you are saying is that server-provided user interfaces have proven
useful on the web because they don't require prior agreement with the
client software about what the user interface will look like. That is
all well and good, but doesn't translate into good practice for machine
to machine communications. When a machine has an atom document it wants
to submit to another machine, it is too late to start messing with the
content. The client machine doesn't know how. It has to rely on out of
band agreement with the server to what is acceptable.

Benjamin.

On 1/4/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> On Wed, 2007-01-03 at 20:06 -0600, Hugh Winkler wrote:
>  > Real world experience: RosettaNet PIP 3A4. Thoroughly specified
>  > schemas describing almost every possible Purchase Order Request and
>  > Response. Guess how long it takes one large computer manufacturer to
>  > shake out enough impedance mismatches to get going with each new
>  > trading partner? 30-60 days, and that is a dedicated team of experts
>  > exchanging test messages, "validating" them, discovering and resolving
>  > the semantic mismatches in even the "valid" documents.

>  Bad standards exist, therefore standards are bad. Nice logic.

I don't think that's a valid conclusion.  RosettaNet is not a bad
standard.  As I wrote in another post, it is the third generation of
ecommerce standards that each tried to learn from and resolve the
problems of the previous generation. Each was better than its
predecessor. So by the Microsoft rule,  RosettaNet should have been
pretty good.

It's just a difficult problem.

On 1/4/07, Bob Haugen <bob.haugen@...> wrote:
> On 1/4/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > On Wed, 2007-01-03 at 20:06 -0600, Hugh Winkler wrote:
> >  > Real world experience: RosettaNet PIP 3A4. Thoroughly specified
> >  > schemas describing almost every possible Purchase Order Request and
> >  > Response. Guess how long it takes one large computer manufacturer to
> >  > shake out enough impedance mismatches to get going with each new
> >  > trading partner? 30-60 days, and that is a dedicated team of experts
> >  > exchanging test messages, "validating" them, discovering and resolving
> >  > the semantic mismatches in even the "valid" documents.
>
> >  Bad standards exist, therefore standards are bad. Nice logic.
>
> I don't think that's a valid conclusion.  RosettaNet is not a bad
> standard.  As I wrote in another post, it is the third generation of
> ecommerce standards that each tried to learn from and resolve the
> problems of the previous generation. Each was better than its
> predecessor. So by the Microsoft rule,  RosettaNet should have been
> pretty good.
>
> It's just a difficult problem.
>
>

Exactly. RosettaNet is a great standard... the apotheosis of this
style of exchanging full documents. My point is that style is not
scalable, and that APP is using the same approach, on a smaller scale.

On 1/4/07, Bob Haugen <bob.haugen@...> wrote:
> On 1/3/07, Hugh Winkler <hughw@...> wrote:
> >  Starry-eyed delusion: A Standards process can capture the union of all
> >  the semantics any server could manifest.
> >  Corollary: Exchanging these documents is "scalable"
> >
> >  Real world experience: RosettaNet PIP 3A4. Thoroughly specified
> >  schemas describing almost every possible Purchase Order Request and
> >  Response. Guess how long it takes one large computer manufacturer to
> >  shake out enough impedance mismatches to get going with each new
> >  trading partner? 30-60 days, and that is a dedicated team of experts
> >  exchanging test messages, "validating" them, discovering and resolving
> >  the semantic mismatches in even the "valid" documents. So that's one
> >  or two months per partner. How long does it take to ramp on just 100
> >  partners? Years. Not  web scale, is it?
>
> That fits with my experience.  Previous ecommerce standards, ANSI X12
> EDI and EDIFACT, were even worse: took months.
>
> Some of the same people have now created UBL: a 4th or 5th generation
> (X12, EDIFACT, RosettaNet, UBL, depending on whether you put ebXML
> into that geneology).  We'll see how quickly new trading partners can
> get going using that.  I think it's less prescriptive than RosettaNet,
> which tried to achieve minimal configuration.
>
>

It would be good to experiment with a forms style using UBL. I think
you could construct forms using UBL components, so that Toshiba could
have their own PO and Hitachi could have another. Purchasing software
would then be able to GET the forms, and complete them, POSTing the
right information in the PO, because the clients know the definitions
in UBL.

Hugh

On 1/4/07, Mark Baker <distobj@...> wrote:
> On 1/4/07, Hugh Winkler <hughw@...> wrote:
> > It would be good to experiment with a forms style using UBL.
>
> http://sourceforge.net/projects/xforms4ubl/
>

Excellent. So all we need to do is define UBL components for the parts
of an atom:entry that don't already have definitions, e.g.
ubl:atom-content... and you can publish to your blog using ubl-aware
clientware, plus you can order a hard disk too!

Hugh

On 1/4/07, Hugh Winkler <hughw@...> wrote:
> It would be good to experiment with a forms style using UBL.

http://sourceforge.net/projects/xforms4ubl/

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Roy said:

> *sigh*

That about sums it up. ;-)

> Just ignore the definition of idempotent in RFC 2616.  Anything
> specified in HTTP that defines how the server shall implement the
> semantics of an interface method is wrong, by definition.  What
> matters is the effect on the interface as expected by the client,
> not what actually happens on the server to implement that effect.

and

> We have to keep dancing around that bush because
> terminology is a committee-driven process.  Everyone has an opinion
> and so no opinion is spec'd consistently.

Reminds me of a post I read the other day on "Why Specs Matter", with an 
amusing binary taxonomy of developers, which lends some insight into why this 
might be the case.  

Found here:

	http://diveintomark.org/archives/2004/08/16/specs

Enjoy!


Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

On 1/4/07, Andrzej Jan Taramina <andrzej@...> wrote:
> Reminds me of a post I read the other day on "Why Specs Matter", with an
> amusing binary taxonomy of developers, which lends some insight into why this
> might be the case.
>
> Found here:
>
> http://diveintomark.org/archives/2004/08/16/specs

More recently, from the same blog:

http://diveintomark.org/archives/2006/12/07/rest-for-toddlers

:-)
Alan Dean

On Jan 3, 2007, at 11:48 PM, Mike Schinkel wrote:

> Roy T. Fielding wrote:
> > The resource in HTTP is the mapping from the entire identifier
> > (including scheme, authority, path, and query) to a set of values.
> > For two resources to be the same, they must map to the same set
> > of values for all time. There is no way to determine that by
> > inspecting the identifiers, aside from scheme-defined equivalence.
>
> I think I get what you are saying, but I want to be sure. Basically  
> you are
> saying that each of the following URLs point to a DIFFERENT  
> resource as far
> as REST is concerned, correct:

No.  Why would I have said "For two resources to be the same, ..." if
I thought that changing a URI always resulted in different resources?
They might be different resources, the client generally won't be able
to figure that out, so the only safe assumption is that they are
different resources until stated otherwise by the server.

This is Web Architecture.  Resources are an abstraction -- a source of
goodness as perceived by the person who linked to that resource that
is in the form of a value-giver over time.  There are no resources on
the Web -- only senders and receivers of representations that have
the effect of evaluating a resource mapping at invocation time,
thereby becoming "the resource" as we perceive it over time even
though we all know it is just a finite data server at any single
point in time.

The ultimate goal is to choose the one true identifier that will
always map to the intended resource, such that the link author (and
the millions of people who subsequently copy or bookmark that link)
never have to change the link. Of course, we rarely achieve the
ultimate goal the first time, and sometimes there are many paths to
the ultimate goal that get explored along the way, and sometimes
people move the goal posts.

If there are many URIs for a given resource, the best implementation
is for all of the other URIs to redirect to the one URI that is
deemed to be "best" for the resource's unique semantics.  The reason
for that is not REST or Web Architecture (though both are specifically
designed to enable it): the reason is network economics as expressed
by power laws, Metcalfe's law, PageRank, and a hundred other
restatements of the factors that place value on social networks.

REST works because it makes absolutely no attempt to understand
what the resource is, how it might be implemented, or the scope of
how it will change over time.  It eliminates the semantic burden of
understanding by focusing only on the interface as a means of hiding
knowledge from the other side, yet communicating all that needs to
be said in the same way that two people communicate -- tossing
representations across the gap with a relatively small number of
pitch inflections to indicate what is expected in return.  In short,
REST doesn't care what the resource is or how many URIs identify
the same resource, because to care would require understanding that
would lead to coupling which is more dangerous than inefficiency.

Such communication theory is a lot more abstract than REST, REST is
a lot more abstract than Web Architecture (URI, HTTP, HTML, ...),
and Web Architecture is somewhat more abstract than any current
implementation of that architecture (Apache httpd, Mozilla Firefox,
etc.).  And yet they all need to influence each other, in various
ways, when we attempt to design changes to a living system.

....Roy

Roy T. Fielding wrote: 
> > Roy T. Fielding wrote:
> > > The resource in HTTP is the mapping from the entire identifier 
> > > (including scheme, authority, path, and query) to a set of values.
> > > For two resources to be the same, they must map to the 
> same set of 
> > > values for all time. There is no way to determine that by 
> inspecting 
> > > the identifiers, aside from scheme-defined equivalence.
> >
> > I think I get what you are saying, but I want to be sure. Basically 
> > you are saying that each of the following URLs point to a DIFFERENT 
> > resource as far as REST is concerned, correct:
> 
> No.  Why would I have said "For two resources to be the same, 
> ..." if I thought that changing a URI always resulted in 
> different resources?
> They might be different resources, the client generally won't 
> be able to figure that out, so the only safe assumption is 
> that they are different resources until stated otherwise by 
> the server.

I guess my terminology was confusing. Are you saying then that I CAN have a
fully RESTful app that uses the following three URLs the same?

	http://www.foo.com
	http://www.foo.com/
	http://www.foo.com/index.php

BTW, I am differentiating from what REST requires of a resource to the
broader view of resources on the web because we all know the web is not 100%
RESTful as globally implemented by many domain holders.

> The ultimate goal is to choose the one true identifier that 
> will always map to the intended resource such that the link 
> author (and the millions of people who subsequently copy or 
> bookmark that link) never have to change the link. 

I think you are coupling constraints. I could easily have three indentifiers
that point to the same resource (as you implied above, I think) that ALL
never change.  I could also limit to one single identifier per resource, and
then arbitrarily change it. So I don't think narrowing the focus to just one
identifier necessarily does any better job of ensuring that that one
identifier never changes. Yes chances are that in some cases one is easier
to keep from changing than multiple, but if the URL authority architects its
site in advance with multiple persistent URLs per resource in mind then five
URLs pointing to the same resource are no less likely to change then two
URLs per resource or even one URLs per resource.

That said, over than the obvious, what's wrong with links changing? And I'm
not being pedantic, I'm exploring out of the box thinking.  Is it bad to
change a link if that link returns a 301 redirect to the new link?  If so,
why?  I have other thoughts on the matter of broken links, but as I plan to
blog them I'll hold them for now; I'll email the list after I make those
posts.

> If there are many URIs for a given resource, the best 
> implementation is for all of the other URIs to redirect to 
> the one URI that is deemed to be "best" for the resource's 
> unique semantics.  The reason for that is not REST or Web 
> Architecture (though both are specifically designed to enable 
> it): the reason is network economics as expressed by power 
> laws, Metcalfe's law, PageRank, and a hundred other 
> restatements of the factors that place value on social networks.

I see the "best practices" you are citing as optimizing for certain benefits
at the expense of others. I'm currently doing research to determine how we
can optimize for both because I don't think we should have to settle for one
and not the other.

> REST works because it makes absolutely no attempt to 
> understand what the resource is, how it might be implemented, 
> or the scope of how it will change over time.  It eliminates 
> the semantic burden of understanding by focusing only on the 
> interface as a means of hiding knowledge from the other side, 
> yet communicating all that needs to be said in the same way 
> that two people communicate -- tossing representations across 
> the gap with a relatively small number of pitch inflections 
> to indicate what is expected in return.  In short, REST 
> doesn't care what the resource is or how many URIs identify 
> the same resource, because to care would require 
> understanding that would lead to coupling which is more 
> dangerous than inefficiency.

That sounds reasonable. What do you consider to be "the pitch inflections?"
Content type? Other?

> Such communication theory is a lot more abstract than REST, 
> REST is a lot more abstract than Web Architecture (URI, HTTP, 
> HTML, ...), and Web Architecture is somewhat more abstract 
> than any current implementation of that architecture (Apache 
> httpd, Mozilla Firefox, etc.).  And yet they all need to 
> influence each other, in various ways, when we attempt to 
> design changes to a living system.

BTW, throughout history there have been "specifications" designed to
constrict human behaviour. One of the better known sets of specifications in
the Western world are "The 10 Commandments" and all it's derivatives. And as
with most other specifications that have followed, including those you
mention, they really were designed for the good of society. 

However as we all knowm people often don't follow them, and sometimes they
have good reasons and sometimes bad. My interest is in finding ways to
either change the enviroment so that the reasons they don't follow the rules
no longer apply, or to augment the rules so that new goals can be achieved
in other ways while still maintaining the fundamental benefits to society.
In cases where the rules are "handed down by God" my approach doesn't play
too well but when we are talking technology one of the beauties is that we
can often add another layer to meet the new goals without sacrificing the
old ones. 

As with any rules or sets of specifications, there are those who are steeped
in them and have working with them for years. Those people have often
unconsciously accepted many constraints. Progress is often made by people
who "don't know any better" than to questions those constraints that have
been unconsciously accepted by so many. Understandably, those with
significant experience are upset by the things that the newcomers question
for hopefully obvious reasons. And the newcomers usually find that the
constraints embraced by the experienced are constraints for good reason. But
every so often the newcomers are able to identify unconsciously accepted
constraints that really were not constraints after all, and this is when
progress and innovation is made.

Roy, I am one of those newcomers and you are clearly highly experienced. I
have identified numerous issues that seem to plague the web community
related to my research on URLs, and I researching ways to address some of
those issues. I ask in advance for you to forgive me of any questions I may
ask or any concepts I may propose now or in the future even if you feel that
you've already been down that path with others. As I go about trying to
identify some of those unconsciously accepted constraints I will undoubtedly
learn the benefits of most of those constaints, but I also hope to uncover
some that really were not constraints at all. Understand I have gained great
respect for you and the community the brief time I've been participating and
that whatever my future involvement, my goal is to ensure that I uphold the
web's principles while doing nothing to harm it either.

Please remember that at one point in time you were the newcomer, and you
have great ideas which turned out to be good. Please give me the same
opportunities you were given to research and then question, and it is
possible I may ultimately make some important contributions myself.  

Thanks for listening.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

On Jan 4, 2007, at 2:16 PM, Roy T. Fielding wrote:

> On Jan 3, 2007, at 11:48 PM, Mike Schinkel wrote:
>
>> Roy T. Fielding wrote:
>>> The resource in HTTP is the mapping from the entire identifier
>>> (including scheme, authority, path, and query) to a set of values.
>>> For two resources to be the same, they must map to the same set
>>> of values for all time. There is no way to determine that by
>>> inspecting the identifiers, aside from scheme-defined equivalence.
>>
>> I think I get what you are saying, but I want to be sure. Basically
>> you are
>> saying that each of the following URLs point to a DIFFERENT
>> resource as far
>> as REST is concerned, correct:
>
> No.  Why would I have said "For two resources to be the same, ..." if
> I thought that changing a URI always resulted in different resources?
> They might be different resources, the client generally won't be able
> to figure that out, so the only safe assumption is that they are
> different resources until stated otherwise by the server.
>
> This is Web Architecture.  Resources are an abstraction -- a source of
> goodness as perceived by the person who linked to that resource that
> is in the form of a value-giver over time.  There are no resources on
> the Web -- only senders and receivers of representations that have
> the effect of evaluating a resource mapping at invocation time,
> thereby becoming "the resource" as we perceive it over time even
> though we all know it is just a finite data server at any single
> point in time.

If I understand this correctly, the term resource in the REST and  
HTTP context means a thing of value as perceived by the people using  
the system. If all you have is a bunch of URIs, you can't make any  
assumptions about whether they refer to the same resource or not. But  
if you have a bunch of URIs plus more semantic information about the  
resources they represent, then you can make such assumptions. In that  
case, Steve should be OK saying things like:

GET 	/resource 	Retrieve the entire resource.  Query parameters may  
be available to retrieve only parts of the resource.

Yes, in hindsight perhaps the HTTP spec shouldn't have said that  
about the query parameters. But Steve can declare in his article that  
for any system that implements his Entity pattern as he defines it,  
all URLs that are identical up to the query parameters refer to the  
same resource. And in my case, I can say that in my architecture an  
article is a resource, and that any article URIs that are identical  
up to the query parameters refer to the same article resource.

Any objections to that way of treating the term resource?

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Hi Roy,

On Jan 3, 2007, at 4:52 PM, Roy T. Fielding wrote:

> The resource in HTTP is the mapping from the entire identifier
> (including scheme, authority, path, and query) to a set of values.
> For two resources to be the same, they must map to the same set
> of values for all time.  There is no way to determine that by
> inspecting the identifiers, aside from scheme-defined equivalence.
>
I assume here by set of "values" you don't mean set of  
representations returned. These are the values as known to the  
server, from which it creates and sends representations down to  
clients. Is that correct?

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Jan 4, 2007, at 2:16 PM, Roy T. Fielding wrote:

> The ultimate goal is to choose the one true identifier that will
> always map to the intended resource, such that the link author (and
> the millions of people who subsequently copy or bookmark that link)
> never have to change the link. Of course, we rarely achieve the
> ultimate goal the first time, and sometimes there are many paths to
> the ultimate goal that get explored along the way, and sometimes
> people move the goal posts.
>
> If there are many URIs for a given resource, the best implementation
> is for all of the other URIs to redirect to the one URI that is
> deemed to be "best" for the resource's unique semantics.  The reason
> for that is not REST or Web Architecture (though both are specifically
> designed to enable it): the reason is network economics as expressed
> by power laws, Metcalfe's law, PageRank, and a hundred other
> restatements of the factors that place value on social networks.

I understand how that should help search engines count how many  
references there are for calculating page rank, but could you  
elaborate how canonical URLs affect "Metcalf's law, power laws, and a  
hunder other restatements..."

I did take the canonical URL thing to heart in our new architecture.  
It may be a bit over-designed but we generate controllers that  
canonicalize by dropping trailing slashes and even reordering the  
query parameters. For example:

http://www.artima.com/articles?t=java&p=4&o=a
http://www.artima.com/articles?p=4&o=a&t=java
http://www.artima.com/articles?t=java&o=a&p=4
http://www.artima.com/articles?p=4&t=java&o=a
http://www.artima.com/articles?o=a&p=4&t=java
http://www.artima.com/articles/?t=java&p=4&o=a
http://www.artima.com/articles/?p=4&o=a&t=java
http://www.artima.com/articles/?t=java&o=a&p=4
http://www.artima.com/articles/?p=4&t=java&o=a
http://www.artima.com/articles/?o=a&p=4&t=java
http://www.artima.com/articles/?o=a&t=java&p=4

All get redirected to:

http://www.artima.com/articles?o=a&t=java&p=4

Currently there is one URI that doesn't get redirected to the  
canonical form. It's on my list to fix that:

http://artima.com/articles?o=a&t=java&p=4

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Bill,

Something that I'm sure confuses a lot of folks is the fact
that in his dissertation, Roy defined "Resource" as a mapping.
A mapping is a relation, not a thing.  But in common usage,
we talk about resources as if they were things.

A la REST, a resource maps individual points in time each to
a set of values which are indeed representations.  A URI
only identifies the mapping.  (BTW, when Roy says the URI
in its entirety maps to a set of values, he is taking a small
liberty with his own REST model, I think.)

When you talk about "part of a resource" realize that formally
you are talking about part of the relation above.  Which part?
The domain (all the mapped time points)?  The range (all the
representations for all times, but without the time dimenstion)?
Certain tuples (all mappings for 1994)?

I am sure you mean none of the above.  In REST, there is no
built-in notion of resource decomposition the way you would
think of decomposing your car or your publications into parts.
And so there can also be no standard for mapping conjugations
of URIs onto them.

Sure hope this helps,

Walden


----- Original Message ----- 
From: "Bill Venners" <bv-svp@...>
To: "Roy T. Fielding" <fielding@...>
Cc: "Steve G. Bjorg" <steveb@...>; <rest-discuss@yahoogroups.com>
Sent: Thursday, January 04, 2007 7:50 PM
Subject: Re: [rest-discuss] Re: Request for feedback: REST for the Rest of 
Us


: Hi Roy,
:
: On Jan 3, 2007, at 4:52 PM, Roy T. Fielding wrote:
:
: > The resource in HTTP is the mapping from the entire identifier
: > (including scheme, authority, path, and query) to a set of values.
: > For two resources to be the same, they must map to the same set
: > of values for all time.  There is no way to determine that by
: > inspecting the identifiers, aside from scheme-defined equivalence.
: >
: I assume here by set of "values" you don't mean set of
: representations returned. These are the values as known to the
: server, from which it creates and sends representations down to
: clients. Is that correct?
:
: Bill
: ----
: Bill Venners
: President
: Artima, Inc.
: http://www.artima.com
:
:
:
:
:
: __________ NOD32 1957 (20070104) Information __________
:
: This message was checked by NOD32 antivirus system.
: http://www.eset.com
:
: 

On Jan 4, 2007, at 4:50 PM, Bill Venners wrote:
> On Jan 3, 2007, at 4:52 PM, Roy T. Fielding wrote:
>
>> The resource in HTTP is the mapping from the entire identifier
>> (including scheme, authority, path, and query) to a set of values.
>> For two resources to be the same, they must map to the same set
>> of values for all time.  There is no way to determine that by
>> inspecting the identifiers, aside from scheme-defined equivalence.
>>
> I assume here by set of "values" you don't mean set of  
> representations returned. These are the values as known to the  
> server, from which it creates and sends representations down to  
> clients. Is that correct?

resource values at time t = { representations | URIs }

also known as representations or redirects.

....Roy

Hi Walden,

On Jan 4, 2007, at 5:12 PM, Walden Mathews wrote:

> Bill,
>
> Something that I'm sure confuses a lot of folks is the fact
> that in his dissertation, Roy defined "Resource" as a mapping.
> A mapping is a relation, not a thing.  But in common usage,
> we talk about resources as if they were things.
>
> A la REST, a resource maps individual points in time each to
> a set of values which are indeed representations.  A URI
> only identifies the mapping.  (BTW, when Roy says the URI
> in its entirety maps to a set of values, he is taking a small
> liberty with his own REST model, I think.)
>
Hmm. Let me ask a pointed question to see if I understand this. By  
Roy's definition of resource as mapping, is it true that:

http://www.artima.com/articles

and

http://www.artima.com/articles?p=4

Must at any time t return the same representation for those two URIs  
to refer to the same resource?

That does not hold true for these two URIs. They would return  
different things at the same time t. (I'm trying to figure out if the  
"collection of articles" conceptual thing equates to a "resource" by  
Roy's definition.)

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com


> When you talk about "part of a resource" realize that formally
> you are talking about part of the relation above.  Which part?
> The domain (all the mapped time points)?  The range (all the
> representations for all times, but without the time dimenstion)?
> Certain tuples (all mappings for 1994)?
>
> I am sure you mean none of the above.  In REST, there is no
> built-in notion of resource decomposition the way you would
> think of decomposing your car or your publications into parts.
> And so there can also be no standard for mapping conjugations
> of URIs onto them.
>
> Sure hope this helps,
>
> Walden
>
>
> ----- Original Message -----
> From: "Bill Venners" <bv-svp@...>
> To: "Roy T. Fielding" <fielding@...>
> Cc: "Steve G. Bjorg" <steveb@...>; <rest- 
> discuss@yahoogroups.com>
> Sent: Thursday, January 04, 2007 7:50 PM
> Subject: Re: [rest-discuss] Re: Request for feedback: REST for the  
> Rest of
> Us
>
>
> : Hi Roy,
> :
> : On Jan 3, 2007, at 4:52 PM, Roy T. Fielding wrote:
> :
> : > The resource in HTTP is the mapping from the entire identifier
> : > (including scheme, authority, path, and query) to a set of values.
> : > For two resources to be the same, they must map to the same set
> : > of values for all time.  There is no way to determine that by
> : > inspecting the identifiers, aside from scheme-defined equivalence.
> : >
> : I assume here by set of "values" you don't mean set of
> : representations returned. These are the values as known to the
> : server, from which it creates and sends representations down to
> : clients. Is that correct?
> :
> : Bill
> : ----
> : Bill Venners
> : President
> : Artima, Inc.
> : http://www.artima.com
> :
> :
> :
> :
> :
> : __________ NOD32 1957 (20070104) Information __________
> :
> : This message was checked by NOD32 antivirus system.
> : http://www.eset.com
> :
> :
>
>
>
>
> Yahoo! Groups Links
>
>
>
>

On Jan 4, 2007, at 5:37 PM, Roy T. Fielding wrote:

> On Jan 4, 2007, at 4:56 PM, Bill Venners wrote:
>> All get redirected to:
>>
>> http://www.artima.com/articles?o=a&t=java&p=4
>
> Why don't you redirect to a permalink style URI?  The ? will reduce
> your cache effectiveness, and is mighty ugly.  Well, I guess for
> "give me a list of java articles sorted by title" that is okay,
> since the articles themselves seem to have permalinks.  Note that
>
>    http://www.artima.com/articles/java/index;date;p4
>
> is short and says more.  YMMV.
>
How does the question mark reduce cache effectiveness nowadays? I  
remember reading that some early cache implementations did not cache  
the responses of URIs with query parameters, because they considered  
that "dynamic content." But I thought that was old history.

As far as the URI you suggest, my hope was to allow users to glean  
insight into the information architecture of the site by the URI. So / 
articles would be a collection of articles. /articles/ 
why_put_and_delete would be an article about PUT and DELETE, etc.  
Anything under /articles/ needs to be an article, because that helps  
users understand the information architecture. So /articles/java  
meaning a collection of articles about Java would break the  
consistency of that mental model for the user. /articles/java should  
be an article about Java.

I also wanted users to be able to chop off pieces of a URI and always  
still get something.  /forums/java_answers/1234/9876 would be a forum  
message. They could chop of the last part, yielding /forums/ 
java_answers/1234, which would give them the forum topic containing  
that message. Chopping again would yield /forums/java_answers, which  
would give them a list of topics in the Java Answers forum. Chopping  
again would yield /forums, which would give them a list of forums. I  
think it is exactly the Container pattern from Scott's article,  
except that I don't support PUT and DELETE.

Each point in the hierarchy is a conceptual thing from the user's  
perspective. /forums is a collection of forums. /forums/java_answers  
is one of those forums, which is a collection of topics. /forums/ 
java_answers/1234 is one of those topics, which is a collection of  
messages. And /forums/java_answers/1234/9876 is one of those  
messages. At the end of any of these "absolute paths" could be a ?  
and some parameters that the user can think of as data that will  
select a particular "view" of the conceptual thing identified by the  
absolute path. I also wanted users to be able to chop off the entire  
query portion too, and still get something.

But I agree ?s and &s and =s are ugly in those URIs. I think I need  
the query parameter keys, but in our new architecture, they are  
always one character. So instead of:

http://www.artima.com/articles?o=a&t=java&p=4

I suppose I could do:

http://www.artima.com/articles;oa;tjava;p4

Shorter, but I'm not sure it's any less ugly. I'm also not sure it is  
as obvious to the user that the conceptual thing identified by this  
URI is http://www.artima.com/articles. Perhaps if there was a  
different character separating the query parameters, as in:

http://www.artima.com/articles;oa,tjava,p4

Or maybe:

http://www.artima.com/articles;o=a,t=java,p=4

Or even:

http://www.artima.com/articles;otp=a,java,4

>> Currently there is one URI that doesn't get redirected to the  
>> canonical form. It's on my list to fix that:
>>
>> http://artima.com/articles?o=a&t=java&p=4
>
> Yep, I have the same problem with aliases to gbiv.com.  Unfortunately,
> my ISP seems to use mod_rewrite's "final rule" within the virtual host
> section, so the easy fix doesn't work for me.
>
One other one that's on my list to fix is this one:

http://www.artima.com/articles?

It doesn't currently redirect to get rid of the ?

Bill

I'd like to get the input from everyone on issues regarding URL structure
choices for REST-based systems.  What are the pros and cons of the following
different sets of URLs:

	http://www.foo.com/users/
	http://www.foo.com/users/john-smith/
	http://www.foo.com/users/john-smith/cell-phone/

Vs.
	http://www.foo.com/?section=users
	http://www.foo.com/?section=users&user=john-smith
	http://www.foo.com/?section=users&user=john-smith&phone=cell-phone

I'm looking to create an exhaustive list of pros & cons.

Thanks in advance for the help.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Steve G. Bjorg wrote:
> I've created a short tutorial on REST and some common 
> resource/service patterns. I would welcome feedback 
> on the accuracy of the content. 

I printed and read you're your article and made a lot of notes for my
questions and comments but the next day I say others had given you a flurry
of feedback.  Rather than duplicate any of their feedback, can you let us
know when you have a revised version so I can compare my notes to see if I
have any outstanding questions/comments? 

One thing I don't think anyone else mentioned was in the section about
"GET", you say:

	"Let's assume we have an image as a resource at
'mywedding.png'"

Yet all your examples with that URL use a ".img" extension:

	GET http://myserver/myphotos/mywedding.img

Was this a typo or am I missing something?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

On Jan 4, 2007, at 4:56 PM, Bill Venners wrote:
 >Roy wrote:
>> If there are many URIs for a given resource, the best implementation
>> is for all of the other URIs to redirect to the one URI that is
>> deemed to be "best" for the resource's unique semantics.  The reason
>> for that is not REST or Web Architecture (though both are  
>> specifically
>> designed to enable it): the reason is network economics as expressed
>> by power laws, Metcalfe's law, PageRank, and a hundred other
>> restatements of the factors that place value on social networks.
>
> I understand how that should help search engines count how many  
> references there are for calculating page rank, but could you  
> elaborate how canonical URLs affect "Metcalf's law, power laws, and  
> a hunder other restatements..."

Too hard to summarize.  This might help explain it.

    http://en.wikipedia.org/wiki/Scale-free_network
    http://en.wikipedia.org/wiki/PageRank

Canonical URLs means that new links are created to the same URL as
previous links, which increases linked-to values, which increases
both the perceived node value of a hub and the corresponding values
of the nodes that link to that hub.

> I did take the canonical URL thing to heart in our new  
> architecture. It may be a bit over-designed but we generate  
> controllers that canonicalize by dropping trailing slashes and even  
> reordering the query parameters. For example:
>
> http://www.artima.com/articles?t=java&p=4&o=a
> http://www.artima.com/articles?p=4&o=a&t=java
> http://www.artima.com/articles?t=java&o=a&p=4
> http://www.artima.com/articles?p=4&t=java&o=a
> http://www.artima.com/articles?o=a&p=4&t=java
> http://www.artima.com/articles/?t=java&p=4&o=a
> http://www.artima.com/articles/?p=4&o=a&t=java
> http://www.artima.com/articles/?t=java&o=a&p=4
> http://www.artima.com/articles/?p=4&t=java&o=a
> http://www.artima.com/articles/?o=a&p=4&t=java
> http://www.artima.com/articles/?o=a&t=java&p=4
>
> All get redirected to:
>
> http://www.artima.com/articles?o=a&t=java&p=4

Why don't you redirect to a permalink style URI?  The ? will reduce
your cache effectiveness, and is mighty ugly.  Well, I guess for
"give me a list of java articles sorted by title" that is okay,
since the articles themselves seem to have permalinks.  Note that

    http://www.artima.com/articles/java/index;date;p4

is short and says more.  YMMV.

> Currently there is one URI that doesn't get redirected to the  
> canonical form. It's on my list to fix that:
>
> http://artima.com/articles?o=a&t=java&p=4

Yep, I have the same problem with aliases to gbiv.com.  Unfortunately,
my ISP seems to use mod_rewrite's "final rule" within the virtual host
section, so the easy fix doesn't work for me.

....Roy

On Jan 4, 2007, at 5:12 PM, Walden Mathews wrote:
> Something that I'm sure confuses a lot of folks is the fact
> that in his dissertation, Roy defined "Resource" as a mapping.
> A mapping is a relation, not a thing. But in common usage,
> we talk about resources as if they were things.

Not really, though I agree most people think that way.  Natural
resources are an abstraction as well -- sure, they are "trees" or
"oil" or "gold" or what-have-you at any given point in time,
but when we say "that land is rich in resources" we are talking
about the ongoing production source of "stuff we want", not
individual trees, barrels, or nuggets.  Likewise, management
often plays allocation games with resources in the abstract
before actually mapping those "resources" to people.  YMMV.

I agree about the confusion. It would have been easier for me to
use a different name, but then people would still think that URLs
identified files.  At least the acronym wouldn't have changed.

....Roy

Bill Venners wrote:
> On Jan 4, 2007, at 5:37 PM, Roy T. Fielding wrote:
> 
>> On Jan 4, 2007, at 4:56 PM, Bill Venners wrote:
>>> All get redirected to:
>>>
>>> http://www.artima.com/articles?o=a&t=java&p=4
>> Why don't you redirect to a permalink style URI?  The ? will reduce
>> your cache effectiveness, and is mighty ugly.  Well, I guess for
>> "give me a list of java articles sorted by title" that is okay,
>> since the articles themselves seem to have permalinks.  Note that
>>
>>    http://www.artima.com/articles/java/index;date;p4
>>
>> is short and says more.  YMMV.
>>
> How does the question mark reduce cache effectiveness nowadays? I  
> remember reading that some early cache implementations did not cache  
> the responses of URIs with query parameters, because they considered  
> that "dynamic content." But I thought that was old history.

If the cache is compliant (and most seem to be reasonably so in this 
regard at least) then the question mark only affects the default 
behaviour in the case of there being no cache-control headers.

On Thu, 2007-01-04 at 16:56 -0800, Bill Venners wrote:
> I did take the canonical URL thing to heart in our new architecture. 
> It may be a bit over-designed but we generate controllers that 
> canonicalize by dropping trailing slashes and even reordering the 
> query parameters. For example:
> http://www.artima.com/articles?t=java&p=4&o=a
> http://www.artima.com/articles?p=4&o=a&t=java
...
> http://www.artima.com/articles/?o=a&t=java&p=4
> All get redirected to:
> http://www.artima.com/articles?o=a&t=java&p=4

I'm not a fan of redirection for redirection's sake. If it makes for a
much simpler server implementation so be it, but in general I think it
is poor manners to ask a client to rephrase a request the server
understands perfectly well.

In all of these cases I would be strongly inclined to process the
request normally and repond with the relevant content. I would try to
include a link in the content and/or headers to the bookmark or
"permalink" url for future reference, but I don't want to clog up the
network with repetitions of the same request through the redirection
mechanism. I see redirection primarily as a mechanism to defer to a
server entity that understands the request properly or to deal with a
deprecated url.

Roy, you wrote:
> No. Why would I have said "For two resources to be the same, ..." if
> I thought that changing a URI always resulted in different resources?
> They might be different resources, the client generally won't be able
> to figure that out, so the only safe assumption is that they are
> different resources until stated otherwise by the server.

I worry about the notion of a resource being too airy-fairy. I take a
fairly simple approach in my conversation. If the urls are different we
are talking about two different resources. It might happen that they
demarcate the same application state, but client's can't know that. I
would suggest that even server's don't really know that. A mapping from
URL to representation might be here today but gone after the restructure
tomorrow. One of the aliases might become a redirection next week.
Severs cannot say with certainty over the long-haul that multiple urls
map to the same application state. In that context I am very wary of
language that talks about two resources being the "same", even if the
might happen to be equivalent for the forseeable future.

I talk about different urls always referring to different resources. At
any particular point in time the url demarcates a specific subset of
application state, though the server is free to change the mapping from
url to application state over time. Interacting with the resource
returns, replaces, adds to, destroys, or otherwise operates on the
demarcated application state by transferring representations of the
state being communicated. Different representations encode the state
being communicated into different document types with different
tradeoffs with respect to fidelity of semantics, document simplicity,
generality of applicability and other design factors.

Benjamin.

On Thu, 2007-01-04 at 06:37 -0600, Hugh Winkler wrote:
> On 1/4/07, Bob Haugen <bob.haugen@...> wrote:
> > On 1/4/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > > On Wed, 2007-01-03 at 20:06 -0600, Hugh Winkler wrote:
> > > > Real world experience: RosettaNet PIP 3A4. Thoroughly specified
> > > > schemas describing almost every possible Purchase Order Request
> and
> > > > Response. Guess how long it takes one large computer
> manufacturer to
> > > > shake out enough impedance mismatches to get going with each new
> > > > trading partner? 30-60 days, and that is a dedicated team of
> experts
> > > > exchanging test messages, "validating" them, discovering and
> resolving
> > > > the semantic mismatches in even the "valid" documents.
> > > Bad standards exist, therefore standards are bad. Nice logic.
> > I don't think that's a valid conclusion. RosettaNet is not a bad
> > standard. As I wrote in another post, it is the third generation of
> > ecommerce standards that each tried to learn from and resolve the
> > problems of the previous generation. Each was better than its
> > predecessor. So by the Microsoft rule, RosettaNet should have been
> > pretty good.
> > It's just a difficult problem.
> Exactly. RosettaNet is a great standard... the apotheosis of this
> style of exchanging full documents. My point is that style is not
> scalable, and that APP is using the same approach, on a smaller scale.

I would suggest that by definition any standard that takes "30-60 days"
of "experts exchanging test messages, "validating" them, discovering and
resolving the semantic mismatches in even the "valid" documents" is a
bad standard. That doesn't mean the people are bad. It doesn't mean that
the ideas were bad. It just means that all the necessary ingredients of
standard prepration haven't come together in that problem domain as yet.

If it is working at all for anyone, I suppose it can't be all bad. Over
several more versions it may either become a good standard or form the
groundwork for a family of good standards. However it can't presently be
called good in the way that html is good. HTML works in a now familar
problem domain and can rely on common understanding and shared
motivation between participants about what features are necessary and
what they should look like. Standards like these can be scaled up with a
minimum of effort to a large number of users.

That is not to say that HTML was always a good standard. It needed to
evolve over time as more users placed more demands on it, and it did. It
also drew on earlier document standards and deployed hypertext systems
as a grounding for development.

Let me take your comments at their merit though. Hugh, you suggest that
the style of communication where people get together and agree on a
document format before communication takes place is not scalable. I'll
pay that in some respects. In the sense that we have clearly have good
standards today that scale up remarkably well, you are clearly mistaken.
However the process of standardisation is only as scalable as available
processes of human interaction and participation. That is to say it
tends to fracture on socio-political grounds.

Business is a hard problem-domain to crack because there are so many
people with different ideas about what business is. They each have their
own ways of working. They have their own management styles, styles of
dealing with clients and suppliers. They have their own vocabularies, so
it is hard coming up with a common vocabulary that means the same thing
to everyone. It's like coming up with a document format for common law
contracts. It can only be defined at a very high level with the real
semantics being hidden somewhere in human-readable text.

Atom is not in the business league. It is smaller and targetted to a set
of people who already know what a "blog" is, and can talk about it in
terms familiar to each other. It has still to pass the test of time that
HTML has and see off challenges such as hAtom, but I do tentatively
consider atom to be a good document standard.

Benjamin.

Bill Venners wrote:

> Hmm. Let me ask a pointed question to see if I understand this. By  
> Roy's definition of resource as mapping, is it true that:
> 
> http://www.artima.com/articles
> 
> and
> 
> http://www.artima.com/articles?p=4
> 
> Must at any time t return the same representation for those two URIs  
> to refer to the same resource?
> 

No, Content negotiation could lead to even 
http://www.artima.com/articles alone returning different representations 
to different clients at the same time.

I think it's helpful to stop trying to imagine what the resource is. See

http://cafe.elharo.com/web/rest-is-like-quantum-mechanics/

All you know is representations, nothing more.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 12/22/06, Hugh Winkler <hughw@...> wrote:
> That darn Google... breaking the web again.

In a fit of irony, even Google is guilty! See the 'delete' link on the
Google Alerts management console...

http://www.google.com/alerts/remove?s={token}

On 1/5/07, Hugh Winkler <hughw@...> wrote:
> Oh -- sorry Alan -- you may be right -- I was commenting on the page I
> got redirected to when I clicked the link -- need to try after
> substituting for the {token} don't I?

Yes - I didn't want to publicise one of my own tokens.

Although it does raise a dialog, if you right-click & copy the link
then put that straight into the address bar (effectively what a robot
would do following hrefs) ... the item is deleted

Yep... GET  on the URL after substituting the token of one of my
alerts, deleted the alert.

On 1/5/07, Hugh Winkler <hughw@...> wrote:
> Oh -- sorry Alan -- you may be right -- I was commenting on the page I
> got redirected to when I clicked the link -- need to try after
> substituting for the {token} don't I?
>
>
> On 1/5/07, Hugh Winkler <hughw@...> wrote:
> > On 1/5/07, Alan Dean <alan.dean@...> wrote:
> > > On 12/22/06, Hugh Winkler <hughw@...> wrote:
> > > > That darn Google... breaking the web again.
> > >
> > > In a fit of irony, even Google is guilty! See the 'delete' link on the
> > > Google Alerts management console...
> > >
> > > http://www.google.com/alerts/remove?s={token}
> > >
> > That one's OK, because it doesn't delete when you follow the link. It
> > invokes an onclick handler that pops up a dialog, "Are you sure you
> > want to delete....?". Only the Javascript function executes the
> > delete.
> >
> > Hugh
> >
>
>
> --
> Hugh Winkler
> Wellstorm Development
>
> http://www.wellstorm.com/
> +1 512 694 4795 mobile (preferred)
> +1 512 264 3998 office
>


-- 
Hugh Winkler
Wellstorm Development

http://www.wellstorm.com/
+1 512 694 4795 mobile (preferred)
+1 512 264 3998 office

Oh -- sorry Alan -- you may be right -- I was commenting on the page I
got redirected to when I clicked the link -- need to try after
substituting for the {token} don't I?


On 1/5/07, Hugh Winkler <hughw@...> wrote:
> On 1/5/07, Alan Dean <alan.dean@...> wrote:
> > On 12/22/06, Hugh Winkler <hughw@...> wrote:
> > > That darn Google... breaking the web again.
> >
> > In a fit of irony, even Google is guilty! See the 'delete' link on the
> > Google Alerts management console...
> >
> > http://www.google.com/alerts/remove?s={token}
> >
> That one's OK, because it doesn't delete when you follow the link. It
> invokes an onclick handler that pops up a dialog, "Are you sure you
> want to delete....?". Only the Javascript function executes the
> delete.
>
> Hugh
>


-- 
Hugh Winkler
Wellstorm Development

http://www.wellstorm.com/
+1 512 694 4795 mobile (preferred)
+1 512 264 3998 office

On 1/5/07, Hugh Winkler <hughw@...> wrote:
> Yep... GET  on the URL after substituting the token of one of my
> alerts, deleted the alert.

:-)

A good lesson on why client-side validation is not to be trusted

On 1/5/07, Alan Dean <alan.dean@...> wrote:
> On 12/22/06, Hugh Winkler <hughw@...> wrote:
> > That darn Google... breaking the web again.
>
> In a fit of irony, even Google is guilty! See the 'delete' link on the
> Google Alerts management console...
>
> http://www.google.com/alerts/remove?s={token}
>
That one's OK, because it doesn't delete when you follow the link. It
invokes an onclick handler that pops up a dialog, "Are you sure you
want to delete....?". Only the Javascript function executes the
delete.

Hugh

On Jan 5, 2007, at 5:40 AM, Elliotte Harold wrote:

> Bill Venners wrote:
>
>> Hmm. Let me ask a pointed question to see if I understand this.  
>> By  Roy's definition of resource as mapping, is it true that:
>> http://www.artima.com/articles
>> and
>> http://www.artima.com/articles?p=4
>> Must at any time t return the same representation for those two  
>> URIs  to refer to the same resource?
>
> No, Content negotiation could lead to even http://www.artima.com/ 
> articles alone returning different representations to different  
> clients at the same time.
>
It is difficult to talk about these things. My intent was to include  
the possibility of content negotiation in my question. A more pointed  
question, then, would be: By Roy's definition of resource as mapping,  
is it true that:

http://www.artima.com/articles
and
http://www.artimal.com/articles?p=4

Must at any time t return the same representation given the same  
request headers to refer to the same resource?

> I think it's helpful to stop trying to imagine what the resource  
> is. See
>
> http://cafe.elharo.com/web/rest-is-like-quantum-mechanics/
>
> All you know is representations, nothing more.
>
I am trying to understand the definition of resource in the HTTP and  
REST context, that's all.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Hi Mike,
> On Jan 4, 2007, at 9:02 PM, Mike Schinkel wrote:
> I'd like to get the input from everyone on issues regarding URL  
> structure
> choices for REST-based systems. What are the pros and cons of the  
> following
> different sets of URLs:

I'm a static resource bigot, so I'll answer from that point of view  
and let someone else defend the other side. :-)
A. Static
> http://www.foo.com/users/
> http://www.foo.com/users/john-smith/
> http://www.foo.com/users/john-smith/cell-phone/
+ shorter
+ implies fixed resources
+ implies a single unique resource

B. Dynamic (Long)
> http://www.foo.com/?section=users
> http://www.foo.com/?section=users&user=john-smith
> http://www.foo.com/?section=users&user=john-smith&phone=cell-phone
I actually think this is the wrong contrast. I would propose instead:

C. Dynamic (Short)
> http://www.foo.com/?user=*
> http://www.foo.com/?user=john-smith
> http://www.foo.com/?user=john-smith&phone=cell-phone
Since "section = users" seems redundant with "user=".

Given "A" and "C", I actually think which is better becomes context- 
dependent. If you have static tree of resources the end user drills  
down, then "A" is the most natural. If you have a huge database where  
the user could be sorting on many different fields, then "C" might be  
the simpler construction.

Hope this helps. :-)

-enp

This is a FAQ, Mike.  I'm sure a search for "query" in the archives
will turn up a gold mine of pros/cons.

If you could put what you find on the RESTwiki (the FAQ page in
particular), it would be appreciated.

Cheers,

Mark.

On 1/5/07, Mike Schinkel <mikeschinkel@...> wrote:
> I'd like to get the input from everyone on issues regarding URL structure
> choices for REST-based systems.  What are the pros and cons of the following
> different sets of URLs:
>
>         http://www.foo.com/users/
>         http://www.foo.com/users/john-smith/
>         http://www.foo.com/users/john-smith/cell-phone/
>
> Vs.
>         http://www.foo.com/?section=users
>         http://www.foo.com/?section=users&user=john-smith
>         http://www.foo.com/?section=users&user=john-smith&phone=cell-phone
>
> I'm looking to create an exhaustive list of pros & cons.
>
> Thanks in advance for the help.
>
> --
> -Mike Schinkel
> http://www.mikeschinkel.com/blogs/
> http://www.welldesignedurls.org/
>
>
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Roy T. Fielding wrote:
> On Jan 3, 2007, at 5:13 PM, Bill de hOra wrote:
>> Roy T. Fielding wrote:
>> >
>> > The resource in HTTP is the mapping from the entire identifier
>> > (including scheme, authority, path, and query) to a set of values.
>>
>> I'm reluctant to quibble with an editor, but I was referring to the
>> means of identification as laid out, and not the substance of the 
>> resource.
> 
> What is the difference?   ;-)

The same as the one between UR and URI :)

Anyway, help me out here - if you're saying the resource identifier 
includes the query part, does that conflict with the wording in 3.2.2, 
(which I read as excluding it), or am I misreading one (or both)?

cheers
Bill

Hugh Winkler wrote:
> 
> 
> On 1/4/07, Bob Haugen <bob.haugen@... 
> <mailto:bob.haugen%40gmail.com>> wrote:
>  > On 1/4/07, Benjamin Carlyle <benjamincarlyle@... 
> <mailto:benjamincarlyle%40optusnet.com.au>> wrote:
>  > > On Wed, 2007-01-03 at 20:06 -0600, Hugh Winkler wrote:
>  > > > Real world experience: RosettaNet PIP 3A4. Thoroughly specified
>  > > > schemas describing almost every possible Purchase Order Request and
>  > > > Response. Guess how long it takes one large computer manufacturer to
>  > > > shake out enough impedance mismatches to get going with each new
>  > > > trading partner? 30-60 days, and that is a dedicated team of experts
>  > > > exchanging test messages, "validating" them, discovering and 
> resolving
>  > > > the semantic mismatches in even the "valid" documents.
>  >
>  > > Bad standards exist, therefore standards are bad. Nice logic.
>  >
>  > I don't think that's a valid conclusion. RosettaNet is not a bad
>  > standard. As I wrote in another post, it is the third generation of
>  > ecommerce standards that each tried to learn from and resolve the
>  > problems of the previous generation. Each was better than its
>  > predecessor. So by the Microsoft rule, RosettaNet should have been
>  > pretty good.
>  >
>  > It's just a difficult problem.
>  >
>  >
> 
> Exactly. RosettaNet is a great standard... the apotheosis of this
> style of exchanging full documents. My point is that style is not
> scalable, and that APP is using the same approach, on a smaller scale.

I'm not sure where to begin with this. I dislike muddled conversations 
when it comes to semantics.

All the business processing standards I've seen are inherently 
non-scalable, if by non-scalable you mean the number of actors that can 
share information without resorting to effort in out of band agreements. 
That XForms has a means of exception management (show it to a person) 
and does schema validation in advance via constraints instead of 
defensive programming doesn't have me thinking it's any more applicable 
or valuable than using Atom - indeed it has me thinking it's going to be 
riddled with security holes because to honor an xform constraint you 
need a trustworthy client.

In the general case this a symbolic AI problem. If you want to move 
further along, the applicable state of the art here are denotational 
semantics as used in KR, RDF interchange, or agent based systems like 
FIPA. No-one seems to be sure how to design such things in a way that 
they garner wide adoption on existing infrastructure.

cheers
Bill

Mike Schinkel wrote:
> I printed and read you're your article and made a lot of notes for my
> questions and comments but the next day I say others had given you a
flurry
> of feedback.  Rather than duplicate any of their feedback, can you
let us
> know when you have a revised version so I can compare my notes to
see if I
> have any outstanding questions/comments? 
> 
> One thing I don't think anyone else mentioned was in the section about
> "GET", you say:
> 
> 	"Let's assume we have an image as a resource at
> 'mywedding.png'"
> 
> Yet all your examples with that URL use a ".img" extension:
> 
> 	GET http://myserver/myphotos/mywedding.img
> 
> Was this a typo or am I missing something?

Yes, that's a typo.  It's fixed now, thanks.

For now, I'm collecting the feedback on the feedback page [1].  I'll
integrate it over the weekend and post about it here when it's ready.

Many thanks to everyone who has taken the time to send me their comments!


Cheers,

- Steve

[1] http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us/Feedback

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Unfortunately, the REST wiki seems to be unreliable as hell (sorry),  
but IIRC (and my bookmark does not deceive me) this

http://rest.blueoxen.net/cgi-bin/wiki.pl?PathsAndQueryStrings

is a page I've found useful in the past.

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/



On Jan 5, 2007, at 6:25 PM, Mark Baker wrote:

> This is a FAQ, Mike. I'm sure a search for "query" in the archives
> will turn up a gold mine of pros/cons.
>
> If you could put what you find on the RESTwiki (the FAQ page in
> particular), it would be appreciated.
>
> Cheers,
>
> Mark.
>
> On 1/5/07, Mike Schinkel <mikeschinkel@...> wrote:
> > I'd like to get the input from everyone on issues regarding URL  
> structure
> > choices for REST-based systems. What are the pros and cons of the  
> following
> > different sets of URLs:
> >
> > http://www.foo.com/users/
> > http://www.foo.com/users/john-smith/
> > http://www.foo.com/users/john-smith/cell-phone/
> >
> > Vs.
> > http://www.foo.com/?section=users
> > http://www.foo.com/?section=users&user=john-smith
> > http://www.foo.com/?section=users&user=john-smith&phone=cell-phone
> >
> > I'm looking to create an exhaustive list of pros & cons.
> >
> > Thanks in advance for the help.
> >
> > --
> > -Mike Schinkel
> > http://www.mikeschinkel.com/blogs/
> > http://www.welldesignedurls.org/
> >
> >
> >
> >
> >
> > Yahoo! Groups Links
> >
> >
> >
> >
>
> -- 
> Mark Baker. Ottawa, Ontario, CANADA. http://www.markbaker.ca
> Coactus; Web-inspired integration strategies http://www.coactus.com
>
> 

On 1/5/07, Bill de hOra <bill@...> wrote:
> Hugh Winkler wrote:

> > Exactly. RosettaNet is a great standard... the apotheosis of this
> > style of exchanging full documents. My point is that style is not
> > scalable, and that APP is using the same approach, on a smaller scale.
>
> All the business processing standards I've seen are inherently
> non-scalable, if by non-scalable you mean the number of actors that can
> share information without resorting to effort in out of band agreements.

Yes, that's what I mean.

> That XForms has a means of exception management (show it to a person)
> and does schema validation in advance via constraints instead of
> defensive programming doesn't have me thinking it's any more applicable
> or valuable than using Atom - indeed it has me thinking it's going to be
> riddled with security holes because to honor an xform constraint you
> need a trustworthy client.

I am wide open to suggestions that Xforms may not be up to the task. I
suggested Xfroms because there is a spec for it, and since it's all
about XML, you can make a small leap and declare that the Relax NG and
the RFC define the meanings of elements. So you can sidestep opening
the semantic web discussion.

Constraints just emulate what an HTML form indicates to humans: The
HTML form puts one line for authors, not 10, so the browser cannot
possibly accept more than a single author to submit to the server.

[Side note about exceptions: even in a big machine to machine system,
exceptional conditions usually have to percolate their way back to a
human for handling. It may just be an error log, and the solution may
be... Dang, our purchasing agent/blog syndicator/whatever needs to
understand this new term the server at XYZ.com is demanding. ]

>
> In the general case this a symbolic AI problem. If you want to move
> further along, the applicable state of the art here are denotational
> semantics as used in KR, RDF interchange, or agent based systems like
> FIPA. No-one seems to be sure how to design such things in a way that
> they garner wide adoption on existing infrastructure.
>

Yeah, well I was hoping this discussion would begin the thinking about
"wide adoption on existing infrastructure".  Because if Xforms isn't
up to it, or if RDF forms cannot be brought along far enough, to
handle a simple little web service like APP, then we'll never see web
services adopted as broadly as the web -- which the purpose of a lot
of discussion on this list.

My thinking is that APP is bite-sized enough to where some small
unambitious forms language could lead the way... "microforms". I don't
think it's going to take an Apollo project and a bunch of egghead
professors to start this work... just another little  brushfire of
web innovation.

Hugh

On Jan 5, 2007, at 4:56 AM, Benjamin Carlyle wrote:

> On Thu, 2007-01-04 at 16:56 -0800, Bill Venners wrote:
>> I did take the canonical URL thing to heart in our new architecture.
>> It may be a bit over-designed but we generate controllers that
>> canonicalize by dropping trailing slashes and even reordering the
>> query parameters. For example:
>> http://www.artima.com/articles?t=java&p=4&o=a
>> http://www.artima.com/articles?p=4&o=a&t=java
> ...
>> http://www.artima.com/articles/?o=a&t=java&p=4
>> All get redirected to:
>> http://www.artima.com/articles?o=a&t=java&p=4
>
> I'm not a fan of redirection for redirection's sake. If it makes for a
> much simpler server implementation so be it, but in general I think it
> is poor manners to ask a client to rephrase a request the server
> understands perfectly well.
>
Well, in my case it makes the server a bit more complicated, not  
simpler. By default using Java servlets my server would process all  
those URIs the same. I had to add code to canonicalize those URIs  
into one URI via redirection. I realized I do one other thing that I  
didn't mention. If a URI comes in with a query param at its default  
value, I redirect to the same URI minus that query param.

I didn't do this for redirection's sake, but for the purpose of  
helping search engines figure out that two different URIs really  
refer to the same thing. If the search engine can't figure out that  
two different URIs refer to the same thing, and half of the inbound  
links use each URI, then Google-like PageRank algos won't put that  
page as high in search results as it would have with a canonical URI.  
So I invested in some code to canonicalize URIs that my  
infrastructure didn't already canonicalize, in the hopes of a pay  
back in increased traffic from search engines.

> In all of these cases I would be strongly inclined to process the
> request normally and repond with the relevant content. I would try to
> include a link in the content and/or headers to the bookmark or
> "permalink" url for future reference, but I don't want to clog up the
> network with repetitions of the same request through the redirection
> mechanism. I see redirection primarily as a mechanism to defer to a
> server entity that understands the request properly or to deal with a
> deprecated url.
>
Since all non-canonical URIs are redirected, it should be highly rare  
that someone would ever link to one of them. So oddly enough by doing  
the redirects, I will actually be preventing people from linking to a  
non-canonical URI, in which case the server would never need to do  
any redirects.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

> Roy, you wrote:
>> No. Why would I have said "For two resources to be the same, ..." if
>> I thought that changing a URI always resulted in different resources?
>> They might be different resources, the client generally won't be able
>> to figure that out, so the only safe assumption is that they are
>> different resources until stated otherwise by the server.
>
> I worry about the notion of a resource being too airy-fairy. I take a
> fairly simple approach in my conversation. If the urls are  
> different we
> are talking about two different resources. It might happen that they
> demarcate the same application state, but client's can't know that. I
> would suggest that even server's don't really know that. A mapping  
> from
> URL to representation might be here today but gone after the  
> restructure
> tomorrow. One of the aliases might become a redirection next week.
> Severs cannot say with certainty over the long-haul that multiple urls
> map to the same application state. In that context I am very wary of
> language that talks about two resources being the "same", even if the
> might happen to be equivalent for the forseeable future.
>
> I talk about different urls always referring to different  
> resources. At
> any particular point in time the url demarcates a specific subset of
> application state, though the server is free to change the mapping  
> from
> url to application state over time. Interacting with the resource
> returns, replaces, adds to, destroys, or otherwise operates on the
> demarcated application state by transferring representations of the
> state being communicated. Different representations encode the state
> being communicated into different document types with different
> tradeoffs with respect to fidelity of semantics, document simplicity,
> generality of applicability and other design factors.
>
> Benjamin.
>
>

Nic James Ferrier wrote:
> John Panzer <jpanzer@...> writes:
>
>   
>> Authentication is a very challenging topic and I think it's one that is 
>> a going to be a gating factor in deployment of more sophisticated web 
>> services of all kinds.  Note that the most used web services today don't 
>> require authentication, and I think that's partly because there isn't a 
>> really good answer for this right now.  Any suggestions?
>>     
>
> I can see where you're coming from but I can't fully agree.
>
> RESTfull authentication is possible (I'm doing it... my app will be
> announced here this week!)
>   
Nic -- any update on your app?  I'm interested to see how you're 
handling these issues.

-- 
Abstractioneer <http://feeds.feedburner.com/aol/SzHO>John Panzer
System Architect
http://abstractioneer.org

: I worry about the notion of a resource being too airy-fairy. I take a
: fairly simple approach in my conversation. If the urls are different we
: are talking about two different resources. It might happen that they
: demarcate the same application state, but client's can't know that. I
: would suggest that even server's don't really know that. A mapping from
: URL to representation might be here today but gone after the restructure
: tomorrow. One of the aliases might become a redirection next week.
: Severs cannot say with certainty over the long-haul that multiple urls
: map to the same application state. In that context I am very wary of
: language that talks about two resources being the "same", even if the
: might happen to be equivalent for the forseeable future.

Problem is, without that "Sameness", there is no notion of identity
at all, and no resource.  Everything is itself and perhaps something and
everything else from time to time.*  Who can live in a universe like
that?  You can't convict a murderer, because it was never him; it was
someone else who happened to "demarcate the same state"...
on that particular day.

* Made me think of "I am the Walrus" :-)

Walden

Hi Walden,

On Jan 5, 2007, at 4:05 PM, Walden Mathews wrote:

> : It is difficult to talk about these things. My intent was to include
> : the possibility of content negotiation in my question. A more  
> pointed
> : question, then, would be: By Roy's definition of resource as  
> mapping,
> : is it true that:
> :
> : http://www.artima.com/articles
> : and
> : http://www.artimal.com/articles?p=4
> :
> : Must at any time t return the same representation given the same
> : request headers to refer to the same resource?
> :
>
> If you're sure you've locked out all variation by that approach, then
> the answer should be yes.  But I don't know for sure that content
> negotiation is deterministic.
>
> A safer way to go is to pretend that you have the all-powerful client
> that is able to fetch all possible representations from both URI at  
> all
> times.  Then for all times t, the set of reps from each URI must
> match.  That's as precise as I can say it without resorting to
> formalisms.
>
OK. Thanks for the explanation.

I think this is the definition from Roy's thesis:

More precisely, a resource R is a temporally varying membership  
function MR(t), which for time t maps to a set of entities, or  
values, which are equivalent. The values in the set may be resource  
representations and/or resource identifiers. A resource can map to  
the empty set, which allows references to be made to a concept before  
any realization of that concept exists -- a notion that was foreign  
to most hypertext systems prior to the Web [61]. Some resources are  
static in the sense that, when examined at any time after their  
creation, they always correspond to the same value set. Others have a  
high degree of variance in their value over time. The only thing that  
is required to be static for a resource is the semantics of the  
mapping, since the semantics is what distinguishes one resource from  
another.

So at any time t, the values in the set must be the same for any two  
URIs that claim to reference the same resource. Therefore page four  
and page one of my articles list are two different resources as the  
term resource is used in REST. And therefore I think that given  
Steve's "REST for the rest of us" article is attempting to explain  
REST, he should perhaps not say things like:

GET 	/resource 	Retrieve the entire resource.  Query parameters may  
be available to retrieve only parts of the resource.

For lack of a better term, and since "resource," "entity" and  
"representation" are taken, I might call the conceptual thing an  
"object" and its query-param-accessed variations "views." /articles  
refers to a conceptual collection of articles object at Artima, and  
you can get different views of that object by adding query  
parameters, such as /articles?p=4 or /articles?t=java. Each one of  
those views is a different resource in REST terms.

Bill

: It is difficult to talk about these things. My intent was to include  
: the possibility of content negotiation in my question. A more pointed  
: question, then, would be: By Roy's definition of resource as mapping,  
: is it true that:
: 
: http://www.artima.com/articles
: and
: http://www.artimal.com/articles?p=4
: 
: Must at any time t return the same representation given the same  
: request headers to refer to the same resource?
: 

If you're sure you've locked out all variation by that approach, then
the answer should be yes.  But I don't know for sure that content
negotiation is deterministic.

A safer way to go is to pretend that you have the all-powerful client
that is able to fetch all possible representations from both URI at all
times.  Then for all times t, the set of reps from each URI must 
match.  That's as precise as I can say it without resorting to 
formalisms.

Walden

Hmm, that's been there more than two years - I pointed it out (and two other
situations in Google's Alert system) as part of an article back in 2004. I
honestly thought they'd fix that - not necessarily because of that article,
but because it's just a bug.
http://www.xml.com/pub/a/2004/12/01/pubsub.html 



> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Alan Dean
> Sent: Friday, January 05, 2007 6:02 AM
> To: rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] An apocryphal example of why GET 
> should be safe ...
> 
> On 12/22/06, Hugh Winkler <hughw@...> wrote:
> > That darn Google... breaking the web again.
> 
> In a fit of irony, even Google is guilty! See the 'delete' 
> link on the Google Alerts management console...
> 
> http://www.google.com/alerts/remove?s={token}
> 
> 
>  
> Yahoo! Groups Links
> 
> 
> 

Bill Venners wrote:

> I am trying to understand the definition of resource in the HTTP and 
> REST context, that's all.

I find it useful to work in a Copenhagen-like model in which there is no 
resource, and no need to define it. All we can observe are the URIs and 
representations. Based on these we can predict server behavior without 
ever understanding what a resource really is. Unlike quantum mechanics, 
it's not true that there really aren't any hidden variables, but it's 
very useful to act as if there aren't any.



-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Hi Rusty,

On Jan 6, 2007, at 7:33 AM, Elliotte Harold wrote:

> Bill Venners wrote:
>
>> I am trying to understand the definition of resource in the HTTP  
>> and REST context, that's all.
>
> I find it useful to work in a Copenhagen-like model in which there  
> is no resource, and no need to define it. All we can observe are  
> the URIs and representations. Based on these we can predict server  
> behavior without ever understanding what a resource really is.  
> Unlike quantum mechanics, it's not true that there really aren't  
> any hidden variables, but it's very useful to act as if there  
> aren't any.
>
I think the way Roy defined resource in his thesis was as the mapping  
over time of the values or entities, the actual data returned. I  
thought that made sense, and it really is something. The resource is  
that mapping over time. He doesn't define it as the conceptual thing  
behind the curtain that whose representations result in that mapping.  
It *is* that mapping.

Bill

On Fri, 2007-01-05 at 14:41 -0600, Hugh Winkler wrote:
> On 1/5/07, Bill de hOra <bill@...> wrote:
> > Hugh Winkler wrote:
> > > Exactly. RosettaNet is a great standard... the apotheosis of this
> > > style of exchanging full documents. My point is that style is not
> > > scalable, and that APP is using the same approach, on a smaller
> scale.
> > All the business processing standards I've seen are inherently
> > non-scalable, if by non-scalable you mean the number of actors that
> can
> > share information without resorting to effort in out of band
> agreements.
> Yes, that's what I mean.
...
> Yeah, well I was hoping this discussion would begin the thinking about
> "wide adoption on existing infrastructure". Because if Xforms isn't
> up to it, or if RDF forms cannot be brought along far enough, to
> handle a simple little web service like APP, then we'll never see web
> services adopted as broadly as the web -- which the purpose of a lot
> of discussion on this list.

But again, it isn't a matter of the protocol being up to it or not. It
is about whether the client is up to it. The thing is that you can't
communicate without human-level agreement. This applies to protocols
built around document standards in which the agreement is encoded
directly into client and server. It also applies to protocols built
around forms. In the forms case the server provides enough information
in the form such that a human-level intelligence can figure out what is
meant by all of the fields and attempt to fill them in correctly. The
form is a user inteface, and the same kind of human intelligence needs
to be applied to any filling in or manipulating any user interface.

The terminolgy has to meet basic criteria of collective understanding
even with human-level intelligence. The human must know what an author
is in order to fill out the author field, and map it first to the
concept of "well, that's me" and then to their own name as they would
like it to appear. They might have to take a guess at how the
information will be used to know what form of their name you want. They
may have to refer to a help page to understand all of the necessary
intricacies involved.

So I think you really want to to ask are the dual queries of "How to we
prevent technology issues getting in the way of human-level agreement?"
and "How do we best achieve human-level agreement in a world of
subcultures and individuals?".

The machine document-exchange style relies on agreement being made
before the communication. The forms-exchange style relies on agreement
being made with a human in the loop during the conversation as they
determine how to fill out the form in the way the form provider
intended. An incorrectly filled-out form is a failure to agree. A
correctly filled-out form is the result of agreement via the form
monalogue being understood sufficiently well by the form user.

I think there is a sliding scale to this. Will all atom publication use
atompub? Of course not. Most servers will allow users to submit new
articles online using their web browser. However, when there is no human
in the loop at the time of submission or it is difficult to engage the
user in the communications process you need prior agreement. Consider
the program that allowed a user to write their article offline. Now the
client has atom-equivalent data to submit. It doesn't want to fill out a
form, and can do very little to have the user submit different content
if the server fails to accept the submission.

You need good agreement where you want documents to be understood for
decades as well. After all, when human agreement is required to be
sustained for a long time it also takes a long time to come to a point
of agreement.

Within the machine document-exchange style there is also a sliding
scale. I could agree between my client software and your server software
on a document format. This wouldn't require standardisation over a large
user base, although we are still defining a standard. This would be our
own vocabulary not understood by anyone else. Essentially, our network
effects would be limited to the size of the network between you and me.

On the other end of the scale are your htmls, atoms and other
widely-agreed document formats. These require a lot more effort to
agree, and more effort to change once the initial agreement has come
about. They will be understood for a long time by a large number of
people. They won't be costly to roll out into new applications. But then
again, they are limited in the set of problems they can solve. They can
only solve problems that affect a majority or significant minority of
the standard's contributors.

If we constrast this scale to the development of human language we can
see that humans generally know a small number of general purpose
languages that can solve common problems. Uncommon problems tend to
require specialised vocaulary. Various sciences and technology problem
domains will often have specific jargon that allows uncommon problems to
be solved. I think that the way we define documents for machines will
eventually follow this kind of trend. The jargon could be defined as
part of problem-specific document standards or as adjuncts to more
general standards.

Perhaps our common language for expressing client/server interaction is
HTML, but within html we might define a special language (hCalendar) for
expressing information in the time and date problem domain. Perhaps
revealingly, this kind of mixed vocabulary set can also be combined with
form submission for very special purpose problem domains that might
apply only to a single server on the Internet. These problem domains
afford the least automation and require the greatest application of
human-level intelligence... but a speical problem domain is a special
problem domain.

I think an important focus for evolving the general concept of document
definition needs to be built around allowing not only evolution of the
global concepts, but inclusion of vocabularies that may be
problem-specific. The main reason that this is difficult is because over
time our perspective on the vocabularies may change. What was once
standard might one day be shelved as a special vocabulary. What was once
specal may become part of a standard vocabulary. This process can be
difficult when various special vocabularies overlap or conflict in any
way.

I think forms are important. Don't get me wrong. However, I think that
the basic approach of using documents to pass information between
machines will be an important one for the forseeable future. These
documents must solve most problems with a general vocabulary, but may
still require special vocabularies to be built on top of the general and
combined in interesting ways. If this makes me sound like I am on the
RDF bandwagon, well.. I'm yet to be sold.

I'm not convinced RDF solves the evolution problem as particular terms
change in meaning or empahsis over time. I'm pretty sure I don't want my
documents to have to define ten namespaces at the top and make sure I
select terms from the appropriate namespace for every element in the
file. Perhaps the problem is as simple as placing a <problem-domain>
marker into atom for any special problem domain, and allowing its
sub-elements to float in and out of the main atom feed and entry
elements over subsequent atom versions. Perhaps a special <vendor>
elment would make sense to collect anything specific to a particular
application. The important thing would be to allow these special
vocabularies to evolve separately to atom proper as required.

Benjamin.

On Fri, 2007-01-05 at 19:15 -0500, Walden Mathews wrote:
> : I worry about the notion of a resource being too airy-fairy. I take a
> : fairly simple approach in my conversation. If the urls are different we
> : are talking about two different resources. It might happen that they
> : demarcate the same application state, but client's can't know that. I
> : would suggest that even server's don't really know that. A mapping from
> : URL to representation might be here today but gone after the restructure
> : tomorrow. One of the aliases might become a redirection next week.
> : Severs cannot say with certainty over the long-haul that multiple urls
> : map to the same application state. In that context I am very wary of
> : language that talks about two resources being the "same", even if the
> : might happen to be equivalent for the forseeable future.
> Problem is, without that "Sameness", there is no notion of identity
> at all, and no resource.  Everything is itself and perhaps something and
> everything else from time to time.*  Who can live in a universe like
> that?  You can't convict a murderer, because it was never him; it was
> someone else who happened to "demarcate the same state"...
> on that particular day.

Well, you can't convict a resource. However you can put a proxy between
the resource and those who it might harm. The proxy could match requests
destined for http://example.com/thecriminal and treat them specially,
for example by rejecting them outright. If correspondance was still
possible via http://example.com/thecriminal? you would need to match
that too, but you might also need to match
http://example.com/thecriminalsbrother who is colluding with the
criminal to allow message exchanges to continue. Are the criminal and
the criminal's brother the same resource? No, though they are equivalent
in this context for the problem the proxy is trying to solve. Are
http://example.com/thecriminal and http://example.com/thecriminal? the
same resource? I would say no. One day the second resource might be
disabled when the bug that caused the urls to be handled equivalently is
fixed. Then they will no longer necessarily require identical treatment.

I don't go for the sameness of resources or urls. I think sameness is a
concept that only really applies to urns in spaces where a single urn
couldn't be specified for technical reasons. Even then, if they are
equivalent... what purposes are they equivalent for? Can you guarantee
that they will be equivalent for every purpose I can conceive of? Same
is too loose a concept for me. I can only really define it one way: Is
the identification either identical or defined by the scheme to be
equivalent?

So in answer to your question, a resource identified by a particular url
is the same as itself. That is all we need for the purposes of identity.
For other purposes we need more problem-specific concepts of equvalence
to make statements that can be understood.

Benjamin.

Benjamin,

In systems design, it is important to collapse concepts which
within the system have no real distinction.  We refactor code,
establish asias lookup schemes, and probably do a whole
raft of other things to factor out redundancy noise in the interest
of simplicity and clarity.

Obsolete stuff should get garbage collected.  In the system
you propose, that can't happen.  You are making identifiers too
important, IMO.  More important than what they identify.

Walden

----- Original Message ----- 
From: "Benjamin Carlyle" <benjamincarlyle@...>
To: "Walden Mathews" <waldenm@...>
Cc: "Bill Venners" <bv-svp@...>; "Roy T. Fielding" 
<fielding@...>; "Mike Schinkel" <mikeschinkel@...>; 
<rest-discuss@yahoogroups.com>
Sent: Saturday, January 06, 2007 11:52 PM
Subject: Re: [rest-discuss] Re: Request for feedback: REST for the Rest of 
Us


: On Fri, 2007-01-05 at 19:15 -0500, Walden Mathews wrote:
: > : I worry about the notion of a resource being too airy-fairy. I take a
: > : fairly simple approach in my conversation. If the urls are different 
we
: > : are talking about two different resources. It might happen that they
: > : demarcate the same application state, but client's can't know that. I
: > : would suggest that even server's don't really know that. A mapping 
from
: > : URL to representation might be here today but gone after the 
restructure
: > : tomorrow. One of the aliases might become a redirection next week.
: > : Severs cannot say with certainty over the long-haul that multiple urls
: > : map to the same application state. In that context I am very wary of
: > : language that talks about two resources being the "same", even if the
: > : might happen to be equivalent for the forseeable future.
: > Problem is, without that "Sameness", there is no notion of identity
: > at all, and no resource.  Everything is itself and perhaps something and
: > everything else from time to time.*  Who can live in a universe like
: > that?  You can't convict a murderer, because it was never him; it was
: > someone else who happened to "demarcate the same state"...
: > on that particular day.
:
: Well, you can't convict a resource. However you can put a proxy between
: the resource and those who it might harm. The proxy could match requests
: destined for http://example.com/thecriminal and treat them specially,
: for example by rejecting them outright. If correspondance was still
: possible via http://example.com/thecriminal? you would need to match
: that too, but you might also need to match
: http://example.com/thecriminalsbrother who is colluding with the
: criminal to allow message exchanges to continue. Are the criminal and
: the criminal's brother the same resource? No, though they are equivalent
: in this context for the problem the proxy is trying to solve. Are
: http://example.com/thecriminal and http://example.com/thecriminal? the
: same resource? I would say no. One day the second resource might be
: disabled when the bug that caused the urls to be handled equivalently is
: fixed. Then they will no longer necessarily require identical treatment.
:
: I don't go for the sameness of resources or urls. I think sameness is a
: concept that only really applies to urns in spaces where a single urn
: couldn't be specified for technical reasons. Even then, if they are
: equivalent... what purposes are they equivalent for? Can you guarantee
: that they will be equivalent for every purpose I can conceive of? Same
: is too loose a concept for me. I can only really define it one way: Is
: the identification either identical or defined by the scheme to be
: equivalent?
:
: So in answer to your question, a resource identified by a particular url
: is the same as itself. That is all we need for the purposes of identity.
: For other purposes we need more problem-specific concepts of equvalence
: to make statements that can be understood.
:
: Benjamin.
:
:
: __________ NOD32 1960 (20070106) Information __________
:
: This message was checked by NOD32 antivirus system.
: http://www.eset.com
:
: 

Roy T. Fielding wrote:
> Canonical URLs means that new links are created to the 
> same URL asprevious links, which increases linked-to values, 
> which increases both the perceived node value of a hub and 
> the corresponding values of the nodes that link to that hub.

What are the tangible places that where having a single canoncial URL
provides benefits?

-- Search engine ranking
-- Router and Proxy caches
-- Anywhere else?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

On Jan 7, 2007, at 10:00 PM, Mike Schinkel wrote:

> Roy T. Fielding wrote:
>> Canonical URLs means that new links are created to the
>> same URL asprevious links, which increases linked-to values,
>> which increases both the perceived node value of a hub and
>> the corresponding values of the nodes that link to that hub.
>
> What are the tangible places that where having a single canoncial URL
> provides benefits?
>
> -- Search engine ranking
> -- Router and Proxy caches
> -- Anywhere else?

Think differently:

The overall value of the graph of resources and links increases as  
hub value increases.
It is not a technical or application question but how useful the  
overall graph is.

Jan


>
> -- 
> -Mike Schinkel
> http://www.mikeschinkel.com/blogs/
> http://www.welldesignedurls.org/
>
>
>
>
> Yahoo! Groups Links
>
>
>

Jan Algermissen wrote:
> > What are the tangible places that where having a single 
> canoncial URL 
> > provides benefits?
> >
> > -- Search engine ranking
> > -- Router and Proxy caches
> > -- Anywhere else?
> 
> Think differently:
> 
> The overall value of the graph of resources and links 
> increases as hub value increases.
> It is not a technical or application question but how useful 
> the overall graph is.

Well, that answer effectively short circuits what I was trying to analyze.
:-( 

The research I am doing is telling me there are benefits to have multiple
URLs, so the requirement to force everything to a canonical URL limits the
ability to pursue those other benefits.  I asked the question to determine
the affected scope in hopes of identifying alternate methods to address the
real concerns.  But if I am only allowed to view as an abstraction, I won't
be able to consider tangible alternate solutions. 

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

P.S. Interestingly, a lot of web principles are based on ideals yet those
ideals are often violated for many different practical reasons. Would be
nice if we could find ways that those ideals would not need to be
violated....

On Sun, 2007-01-07 at 10:44 -0500, Walden Mathews wrote:
> : So in answer to your question, a resource identified by a particular
url
> : is the same as itself. That is all we need for the purposes of identity.
> : For other purposes we need more problem-specific concepts of equvalence
> : to make statements that can be understood.

> In systems design, it is important to collapse concepts which
> within the system have no real distinction.  We refactor code,
> establish asias lookup schemes, and probably do a whole
> raft of other things to factor out redundancy noise in the interest
> of simplicity and clarity.
> 
> Obsolete stuff should get garbage collected.  In the system
> you propose, that can't happen.  You are making identifiers too
> important, IMO.  More important than what they identify.

Would you mind elaborating? I'm not sure I understand what you are
intending to say. What I am suggesting is that different urls are always
different identifiers, even when they identify loosely- or closely-
related resources.

I see this suggestion as a practical breakdown of the system. No node in
the system can sustainably claim equivalence of two urls except as
defined by scheme without adding "for my purposes". The server can talk
about the sameness of two urls for the purpose of causing them to use
the same processing for requests. That is ephemeral. The authentication
proxy can talk about sameness of two urls for the purposes of access
control. That too is emphemeral and is a distinct concept. A client can
talk about the sameness of urls for the purposes of its usage. Same is a
short-lived perspective-specific notion. Even the notion of an
identified resource being the same over time depends on the context in
which the word "same" is used.

I think you are suggesting that a eternity of association between url
and resource is too much. I'm not sure things are so simple. URLs can be
deprecated and fade into obscurity, then be brought back to life in a
different form. Perhaps the resource at the url is no longer the same
from particular perspectives or even from any perspective, but the value
in calling it a different resource is probably minimal at that point.
Certainly, breaking a sameness assumption about a resource anywhere in
the system will have negative effects on the nodes that rely on that
sameness. It is sometimes hard to judge what those effects will be. It
is sometimes hard to gauge what assumptions are being made in the wild.

So, "same" for the purpose of identity and "same" for other purposes
don't have to be concepts that line up. The identified resource is the
same when the same url is used. We know that. Past that point we can't
predict what other kinds of sameness will be applicable. We can only
rely on social contract with the resource provider that obvious sameness
is left intact. Social contracts can last for a long time, but we can't
rule out the possibility that one day the http://google.com resources
won't be sold out to a goggle retailer and change meanings for most
useful purposes.

So I do suggest that a url identifies a particular resource, and that
other urls identify different resources. The mapping of that resource to
representations can change over time to break all of our sameness
assumptions if it wants to... but I suggest that sameness of
identification is the only impartial and absolute way to express the
sameness concept. A resource is many things to many people. Is
<http://google.com.au/> the same as <http://google.com/>? It is for me,
but likely not for you.

It is difficult to carry on a conversation about which urls identify the
same resource if a resource is simply "what you make of it" from any
appropriate perspective. Take the google example again. To me they both
express the concept of "google's search page", however to someone from
abroad a different set of urls would fall into the set. It is difficult
to talk about which urls identify different resources.

I see identity as the rock of vocabulary that allows unambigous
conversations to be had about what resources are and how we should
interact with them. You can then move on to definitions of resources
that help express the meaning of the classic HTTP methods:

* A resource is a selection of application state that can be operated on
by verbs such as the HTTP methods. Different resources may select or
demarcate the same or overlapping application state.
* The selection is expressed as an identifier. The server determines
what mapping should apply from this identifier its objects, tables, or
other accessible data or state at all times. This mapping is subject to
change according to the server's requirements which will partially
reflect the requirements of its clients.
* GET requests a representation of the selected application state in one
of possibly several representations. Different representations will
likely retain different levels of semantic fidelity of the actual
application state.
* PUT replaces the selected application state with the state transferred
in the request's representation
* POST adds the state transferred in the request's representation to the
server's state.
* DELETE is a PUT of the null state to the resource
* The server may handle the requests in a number of ways that don't
exactly match the request. Business logic can come into effect to have
arbitrary knock-on consequences, including those that leave the
identified resource in a different state to that intended by the method.
Some consequences can be communicated back to the client as part of the
request, for example a "created" or "no content" response can be
returned to a POST request.

This set of definitions defines the resource concept in a different way
to REST, and I think forms a subset of theoretical REST that can form
the basis of discussion about which methods a particular architecture
should have. It lies somewhere between the real web and REST theory as a
practical bridge of good web style.

Benjamin.

Benjamin Carlyle wrote:
> I see this suggestion as a practical breakdown of the system. No node in
> the system can sustainably claim equivalence of two urls except as
> defined by scheme without adding "for my purposes".

Sure it can.

Just like I can say that the identifiers "Norma Jean Mortenson" and 
"Marilyn Monroe" identify the same person.

Of course I can also say that "Marilyn Monroe" and "Marilyn Manson" 
identify the same person. The fact that a claim that two URIs identify 
the same resource can be wrong is a different matter to whether they 
actually can do so.

Benjamin,

This is getting way to complicated.  Let's clear away some of the
distractions and deal with a very simple case:

Let's say you have a static page you intend to host forever, and
you have one and only one representation you send for that page.
You don't honor POST, PUT or DELETE (or any other unsafe
method that may appear someday).  But, for reasons we don't
care about right now, you support two URL's for that page:

http://benjamin.com/thepage and http://benjamin.com/page1

Clearly you have two identifiers here.  But are you willing to
allow that they simply identify the same resource, and so there are
not two resources, just one?  If not, why?

Walden

Hi Mike,

On Jan 7, 2007, at 1:47 PM, Mike Schinkel wrote:

> The research I am doing is telling me there are benefits to have  
> multiple
> URLs, so the requirement to force everything to a canonical URL  
> limits the
> ability to pursue those other benefits.  I asked the question to  
> determine
> the affected scope in hopes of identifying alternate methods to  
> address the
> real concerns.  But if I am only allowed to view as an abstraction,  
> I won't
> be able to consider tangible alternate solutions.
>
Could you elaborate on those "benefits to have multiple URL's"? I'm  
curious what they are.

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Bill Venners wrote:
> > The research I am doing is telling me there are benefits to have 
> > multiple URLs, so the requirement to force everything to a 
> canonical 
> > URL limits the ability to pursue those other benefits.  I asked the 
> > question to determine the affected scope in hopes of identifying 
> > alternate methods to address the real concerns.  But if I am only 
> > allowed to view as an abstraction, I won't be able to consider 
> > tangible alternate solutions.
> >
> Could you elaborate on those "benefits to have multiple 
> URL's"? I'm curious what they are.

I can give you one easy example, but the other I'm still researching and
will require more background. I plan to cover them on the WDUI Blog[1] when
I have the research complete and I have published enough pre-requisite
material.  

But in a nutshell, for the one example the benefits are URL structure that
models the website's structure and contributing to a more usable website and
more directly usable URL structure.  Hierarchies are wonder structuring
mechanisms for helping humans conceptualize and navigate complex and/or
large amounts of information. However, there are few true hierarchies; most
are just presented as hierarchies to help humans conceptualize. Heirachy's
can provide websites with a useful organizational structure along with
easy-to-navigate URLs so users can see the URLs as they navigate, and hack
to go up and guess to go down or across. Multiple URLs are needed to reach
the same location with the only difference at the root node being the
breadcrumbs.

I could easily give hundreds of examples (and I do mean hundreds; I expect
the range of potential examples possibly in 5 digits if not 6) of how this
could be used.  For one example let's look at a list of representative for
the United States Congress.  I'm using URI Templates[1] to describe the
potential URLs.  Each of the following points to  a representative, but the
drill-down path is different:

http://www.congress.info/house/{state}/{district}/{congress}/
http://www.congress.info/house/{state}/{congress}/{district}/
http://www.congress.info/house/{congress}/{state}/{district}/
http://www.congress.info/{state}/{congress}/house/{district}/
http://www.congress.info/{state}/house/{congress}/{district}/
http://www.congress.info/{state}/house/{district}/{congress}/
http://www.congress.info/{congress}/{state}/house/{district}/
http://www.congress.info/{congress}/house/{state}/{district}/
http://www.congress.info/{congress}/{state}/{district}/

http://www.congress.info/house/{representative}
http://www.congress.info/house/{congress}/{representative}
http://www.congress.info/house/{congress}/{state}/{representative}
http://www.congress.info/house/{state}/{representative}
http://www.congress.info/house/{state}/{district}/{representative}

http://www.congress.info/{state}/{representative}
http://www.congress.info/{state}/{congress}/{representative}
http://www.congress.info/{state}/{district}/{representative}
http://www.congress.info/{state}/house/{congress}/{representative}
http://www.congress.info/{state}/house/{district}/{representative}
http://www.congress.info/{state}/{congress}/house/{representative}
http://www.congress.info/{state}/{district}/house/{representative}

And each of these URLS takes the user same resource given the same values
for the URI Template variables:

http://www.congress.info/senate/{state}/{class}/{congress}/
http://www.congress.info/senate/{state}/{congress}/{class}/
http://www.congress.info/senate/{congress}/{state}/{class}/
http://www.congress.info/{state}/{congress}/senate/{class}/
http://www.congress.info/{state}/senate/{congress}/{class}/
http://www.congress.info/{state}/senate/{class}/{congress}/
http://www.congress.info/{congress}/{state}/senate/{class}/
http://www.congress.info/{congress}/senate/{state}/{class}/
http://www.congress.info/{congress}/{state}/{class}/

http://www.congress.info/senate/{representative}
http://www.congress.info/senate/{congress}/{representative}
http://www.congress.info/senate/{congress}/{state}/{representative}
http://www.congress.info/senate/{state}/{representative}
http://www.congress.info/senate/{state}/{class}/{representative}

http://www.congress.info/{state}/{representative}
http://www.congress.info/{state}/{congress}/{representative}
http://www.congress.info/{state}/{class}/{representative}
http://www.congress.info/{state}/senate/{congress}/{representative}
http://www.congress.info/{state}/senate/{class}/{representative}
http://www.congress.info/{state}/{congress}/senate/{representative}
http://www.congress.info/{state}/{class}/senate/{representative}

The variables:

{congress} - the congress number; every two years there's a new one.
Currently it is 110.
{state} - two character state code.
{district} - the number with a prefix (1st, 2nd, 3rd, etc.) identifying the
district for that state (you'll note this is always subbordinate to {state})
{class} - the class (I, II, or III) for the senator. Every two years there
is a new class and then it repeats at year six. A state has two classes of
senators at any given time. (you'll note this is always subbordinate to
{state})
{representative} - The canonicalized version of the respresentative's name.
Of course these might need a strategy for disambiguation but I ignored that
as it is an irrelevent detail for our discussion.

The above may look overwhelming, but realize that the user would only ever
see one page at a time, and would rarely ever travel down alternate path,
only the path that made sense to them while they were looking for the
information; once they found it why would they continue looking?  But with
this it would give them the ability to drill down in another order that made
sense to them.

And just so you can see it in a not abstract form, here are all the
potential drill-down URLs for my congressman:

http://www.congress.info/house/ga/5th/110/
http://www.congress.info/house/ga/110/5th/
http://www.congress.info/house/110/ga/5th/
http://www.congress.info/ga/110/house/5th/
http://www.congress.info/ga/house/110/5th/
http://www.congress.info/ga/house/5th/110/
http://www.congress.info/110/ga/house/5th/
http://www.congress.info/110/house/ga/5th/
http://www.congress.info/110/ga/5th/

http://www.congress.info/house/john-lewis/
http://www.congress.info/house/110/john-lewis/
http://www.congress.info/house/110/ga/john-lewis/
http://www.congress.info/house/ga/john-lewis/
http://www.congress.info/house/ga/5th/john-lewis/

http://www.congress.info/ga/john-lewis/
http://www.congress.info/ga/110/john-lewis/
http://www.congress.info/ga/5th/john-lewis/
http://www.congress.info/ga/house/110/john-lewis/
http://www.congress.info/ga/house/5th/john-lewis/
http://www.congress.info/ga/110/house/john-lewis/
http://www.congress.info/ga/5th/house/john-lewis/

If, as a typical web user I was drilling down any of those URLs to find John
Lewis' page and was redirected me to the "canonical" URL it would be totally
disorienting and a bad UI IMO. And which one would be canonical anyway?

Clearly the "only one canonical URL" guidance isn't followed 100%, and I
believe that is because the guidance isn't flexible enough to allow
alternately beneficial use cases. So I believe we should be able to question
the guidance of because the guidance really is an implementation detail.
Instead we should be able to look more abstractly at the problem and see if
we can achieve the outcomes the guidance seeks to achieve using alternate
means.  Note I didn't say "ignore" the guidance, I said "question it" in
hopes to find a better solution for future guidance.  

I have several different ways to potentially address these concerns, but I
haven't researched them enough so I let those wait. Besides, this email is
far too long already. ;-)

======

So... now that I've (at least attempted) to answer your question, can you
help me with mine?  What are some of the benefits of Canonical URLs besides
caching and search engine optimization?  And you could even elaborate on the
benefits to caching and search engine optimization too. Thanks in advance.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-00.txt

On 1/8/07, Mike Schinkel <mikeschinkel@...> wrote:

> And you could even elaborate on the
benefits to caching and search engine optimization too. Thanks in advance.

Nice articles by Mark Nottingham:

http://www.mnot.net/cache_docs/
http://www.mnot.net/blog/2005/11/26/caching

GWA is a popularization of caches:
http://google.blognewschannel.com/index.php/archives/2005/05/04/google-web-accelerator/

Squid's a free proxy/cache, so if you google it you might find some
useful  remarks on caching there. I guess Akamai's still going... I'm
a little out of touch .

Hugh

Mike,

: But in a nutshell, for the one example the benefits are URL structure that
: models the website's structure and contributing to a more usable website 
and
: more directly usable URL structure.

It's not clear who reaps these "benefits".  But I think you are
trying to design a web in which clients learn you rules of hierarchy
and then navigate your site by synthesizing URL's by following
the rules.

Meanwhile, URIs are supposed to be opaque from the client
angle, and it should by hypertext that is guiding them along the
path from one resource to the next.  Have you read up much on
these concepts?

Walden

Hi Walden,

On Jan 8, 2007, at 4:14 PM, Walden Mathews wrote:

> Mike,
>
> : But in a nutshell, for the one example the benefits are URL  
> structure that
> : models the website's structure and contributing to a more usable  
> website
> and
> : more directly usable URL structure.
>
> It's not clear who reaps these "benefits".  But I think you are
> trying to design a web in which clients learn you rules of hierarchy
> and then navigate your site by synthesizing URL's by following
> the rules.
>
> Meanwhile, URIs are supposed to be opaque from the client
> angle, and it should by hypertext that is guiding them along the
> path from one resource to the next.  Have you read up much on
> these concepts?
>
URIs are supposed to be opaque from the client program perspective,  
but may not be opaque from the client user perspective. People may  
use the URI to glean information about the information architecture  
of the site. Jakob Nielsen talks about this topic here:

http://www.useit.com/alertbox/990321.html

In observing my own behavior while using other people's web sites, I  
noticed I occasionally find myself hacking off pieces of a URI in the  
hopes of finding something conceptually higher up in the hierarchy.  
It usually didn't work, but I tried. I did not add things to URIs,  
but I did try to subtract things. I want URI hacking that to always  
work at the websites whose URIs and information architecture I  
design. Where I depart from Mike's approach is that I would still  
pick one hierarchy from his many possibilities, and have one  
canonical URI for each resource.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Hi Mike,

On Jan 8, 2007, at 11:22 AM, Mike Schinkel wrote:

> Bill Venners wrote:
>>> The research I am doing is telling me there are benefits to have
>>> multiple URLs, so the requirement to force everything to a
>> canonical
>>> URL limits the ability to pursue those other benefits.  I asked the
>>> question to determine the affected scope in hopes of identifying
>>> alternate methods to address the real concerns.  But if I am only
>>> allowed to view as an abstraction, I won't be able to consider
>>> tangible alternate solutions.
>>>
>> Could you elaborate on those "benefits to have multiple
>> URL's"? I'm curious what they are.
>
> I can give you one easy example, but the other I'm still  
> researching and
> will require more background. I plan to cover them on the WDUI Blog 
> [1] when
> I have the research complete and I have published enough pre-requisite
> material.
>
> But in a nutshell, for the one example the benefits are URL  
> structure that
> models the website's structure and contributing to a more usable  
> website and
> more directly usable URL structure.  Hierarchies are wonder  
> structuring
> mechanisms for helping humans conceptualize and navigate complex  
> and/or
> large amounts of information. However, there are few true  
> hierarchies; most
> are just presented as hierarchies to help humans conceptualize.  
> Heirachy's
> can provide websites with a useful organizational structure along with
> easy-to-navigate URLs so users can see the URLs as they navigate,  
> and hack
> to go up and guess to go down or across. Multiple URLs are needed  
> to reach
> the same location with the only difference at the root node being the
> breadcrumbs.
>
I think I understand. Design is about making tradeoffs, and there are  
several of them here. First of all, as I think you've pointed out you  
could have all of your various hierarchies to navigate down, but at  
the end when you get to the endpoint, you could redirect to a  
canonical form. If you don't have canonical URIs, then you need not  
jolt the user by that redirect at the end, which may be a usability  
plus, but you may make it harder to find the page via search engines,  
which is a usability minus (and probably a business minus for your  
website).  It is also a caching minus, because the cache won't know  
it already has something that came via a different URI. That can be a  
usability minus in the form of slower perceived response time, and a  
business minus in terms of higher bandwidth costs. As a result, I'd  
probably lean towards having canonical URIs.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Bill,

: URIs are supposed to be opaque from the client program perspective,  
: but may not be opaque from the client user perspective. People may  
: use the URI to glean information about the information architecture  
: of the site. Jakob Nielsen talks about this topic here:
: 
: http://www.useit.com/alertbox/990321.html

Webarch [1] is pretty clear on the topic, though.  Agents should
not infer properties from the URI, and "agents" means both people
and machines.

[1] http://www.w3.org/TR/webarch/#uri-opacity

: 
: In observing my own behavior while using other people's web sites, I  
: noticed I occasionally find myself hacking off pieces of a URI in the  
: hopes of finding something conceptually higher up in the hierarchy.  
: It usually didn't work, but I tried. I did not add things to URIs,  
: but I did try to subtract things. I want URI hacking that to always  
: work at the websites whose URIs and information architecture I  
: design. Where I depart from Mike's approach is that I would still  
: pick one hierarchy from his many possibilities, and have one  
: canonical URI for each resource.

Why design to such a limited audience?  Why not improve the
representations (i.e., linking) instead?

Walden

On Jan 8, 2007, at 3:58 AM, Benjamin Carlyle wrote:
> I see identity as the rock of vocabulary that allows unambigous
> conversations to be had about what resources are and how we should
> interact with them. You can then move on to definitions of resources
> that help express the meaning of the classic HTTP methods:
...
> This set of definitions defines the resource concept in a different  
> way
> to REST, and I think forms a subset of theoretical REST that can form
> the basis of discussion about which methods a particular architecture
> should have. It lies somewhere between the real web and REST theory  
> as a
> practical bridge of good web style.

Perhaps you should consider what the purpose of these definitions
may be, and what it is you are trying to describe.

REST is a model of an idealized Web application that attempts to
maximize a particular set of properties that I consider to be
the "most important properties" of the Web as a whole.  Its purpose
is to guide architecture decisions in light of that model, so that
I can avoid breaking the important bits while developing the
architecture and so that developers can understand the
important bits when developing applications.

The problem with your model is that it doesn't respect reality.
By axiomatizing away the notion of resource equivalence you simplify
the model, but then your model is incapable of explaining the
information theoretic properties of the Web that I just finished
describing.  In your model, URI aliases are not an issue because
they don't exist.  In the REST model, URI aliases are an issue
because they reduce the perceived importance of a given resource
and reduce the efficiency of caching resource representations.

REST teaches the architect that reducing aliases will result in a
more efficient system, whereas your model just assumes such a
reduction is impossible.  Google search ranking and duplicate result
presentation emphasize the same characteristics as the REST model
because those are characteristics of the information space
as we know it (the Web).  And you say that your model is somewhere
between the "real Web" and REST theory?  Wrong.  The Web is a lot
more than the sum of client-server interaction.

So, the question then isn't how you might define resources.  The
question is what do you intend to accomplish by doing so?  There
are many ways to look at any given system, particularly when
focusing on only one of the components.  An abstraction like REST
is supposed to help the designer identify mismatches in the
architecture.  Perhaps you don't see the problem because you
aren't applying your model to the Web as a whole, but rather
something more limited (such as a server-side development
framework)?

....Roy

Hi Walden,

On Jan 8, 2007, at 5:37 PM, Walden Mathews wrote:

> Bill,
>
> : URIs are supposed to be opaque from the client program perspective,
> : but may not be opaque from the client user perspective. People may
> : use the URI to glean information about the information architecture
> : of the site. Jakob Nielsen talks about this topic here:
> :
> : http://www.useit.com/alertbox/990321.html
>
> Webarch [1] is pretty clear on the topic, though.  Agents should
> not infer properties from the URI, and "agents" means both people
> and machines.
>
Hmm. You're right that that document defines agents as both software  
and people, but I suspect most web users haven't read that document  
and may not know to not infer anything from URIs. My belief is that  
people do use the URI for clues as to information architecture, and  
therefore I think it is appropriate to design URIs with that in mind.

> [1] http://www.w3.org/TR/webarch/#uri-opacity
>
> :
> : In observing my own behavior while using other people's web sites, I
> : noticed I occasionally find myself hacking off pieces of a URI in  
> the
> : hopes of finding something conceptually higher up in the hierarchy.
> : It usually didn't work, but I tried. I did not add things to URIs,
> : but I did try to subtract things. I want URI hacking that to always
> : work at the websites whose URIs and information architecture I
> : design. Where I depart from Mike's approach is that I would still
> : pick one hierarchy from his many possibilities, and have one
> : canonical URI for each resource.
>
> Why design to such a limited audience?  Why not improve the
> representations (i.e., linking) instead?
>
Mike can do that too, but all those things need to be at some URI  
each, so why not select a canonical URI for each resource that may  
help users figure out where they are in his information architecture.  
Users aren't depending on a URI meaning what they guess it means.  
They just try it and see if the representation matched their  
expectations. If it doesn't, they will quickly try something else. It  
is the representation that they ultimately depend on.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Jan 8, 2007, at 2:18 PM, Hugh Winkler wrote:

> On 1/8/07, Mike Schinkel <mikeschinkel@...> wrote:
>
>> And you could even elaborate on the
> benefits to caching and search engine optimization too. Thanks in  
> advance.
>
> Nice articles by Mark Nottingham:
>
> http://www.mnot.net/cache_docs/
>
This doc says:

must-revalidate � tells caches that they must obey any freshness  
information you give them about a representation. HTTP allows caches  
to serve stale representations under special conditions; by  
specifying this header, you�re telling the cache that you want it to  
strictly follow your rules.

Could someone enlighten me, or point me to such enlightenment, what  
the special conditions are that a cache could serve stale data, and  
why I'd want to say must-revalidate to prevent this? Also, when might  
I want to say proxy-revalidate instead?

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On 1/8/07, Walden Mathews <waldenm@...> wrote:
> Bill,
>
> : URIs are supposed to be opaque from the client program perspective,
> : but may not be opaque from the client user perspective. People may
> : use the URI to glean information about the information architecture
> : of the site. Jakob Nielsen talks about this topic here:
> :
> : http://www.useit.com/alertbox/990321.html
>
> Webarch [1] is pretty clear on the topic, though.  Agents should
> not infer properties from the URI, and "agents" means both people
> and machines.
>
> [1] http://www.w3.org/TR/webarch/#uri-opacity

And if I understand Roy[1] correctly, the only constraint is that
agents should not INFER properties from the URI.  As long as things
are explicitly defined (by spec, by the server, or otherwise), agents
can and do make use of information embedded in the URI.

[1]http://tech.groups.yahoo.com/group/rest-discuss/message/5369

--Chuck

Hugh Winkler wrote:
> Nice articles by Mark Nottingham:
> 
> http://www.mnot.net/cache_docs/

Damn that's a lot to read!!!  
But seriously, thanks. :-)   

> Squid's a free proxy/cache, 

Interesting. I'm definitely going to check that out. Thanks.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Bill Venners wrote:
> First of all, as I think 
> you've pointed out you could have all of your various 
> hierarchies to navigate down, but at the end when you get to 
> the endpoint, you could redirect to a canonical form. If you 
> don't have canonical URIs, then you need not jolt the user by 
> that redirect at the end, which may be a usability plus, but 
> you may make it harder to find the page via search engines, 
> which is a usability minus (and probably a business minus for 
> your website).  

Well, I want to explore why it is harder for search engines to find that
page. And can we change that?  Or consider the problem from a different
perspective?  Google tweaks their algorithms quarterly.  Why could they not
include an update given new guidance?  The rest would follow.    

> It is also a caching minus, because the cache 
> won't know it already has something that came via a different 
> URI. That can be a usability minus in the form of slower 
> perceived response time, and a business minus in terms of 
> higher bandwidth costs. 

Again, I'd like to explore why that is and see if there are not new ways to
look at the problem.

> As a result, I'd probably lean 
> towards having canonical URIs.

As you state, it is a tradeoff.  But in my research I'm seeing too many
benefits to ignore so I'm motivated to come up with any alternate approach
with less trade offs.  BTW, it's hard to convey the full depth and breadth
of what I've learn because I haven't finished my research. I know
intuitively but am not ready to make the full case on paper. I think it was
my mistake to give you the courtsey of an explanation before I was prepared
because you've now gone away unconvinced and (by human nature) are less
likely to reconsider the issue when I publish.  FWIW.  (But at least you
were respectful about it. :) 

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Walden Mathews wrote: 
> Mike,
> 
> : But in a nutshell, for the one example the benefits are URL 
> structure that
> : models the website's structure and contributing to a more 
> usable website and
> : more directly usable URL structure.
> 
> It's not clear who reaps these "benefits".  But I think you 
> are trying to design a web in which clients learn you rules 
> of hierarchy and then navigate your site by synthesizing 
> URL's by following the rules.

The benefits accrue to web users but more so to website owners.  For web
users it increases the intuitiveness of a website and, if they are bloggers
or cite links in some other activity, it makes it easier for them to do so.

For one example, look at Wikipedia's URLs; is it a wonder there are linked
as often at they are? 

	http://en.wikipedia.org/wiki/REST

IF it were instead

	
http://www.wikipedia.org/topic.php?topicID=7937521&lang=en-US&source-ie7&en-
US&ie=utf8&oe=utf8

I can guarantee you it would not be linked as much.  I could remember and
compose the former, there is no way I could remember the latter (FYI, I
frequently like to Wikipedia just by prefixing a term with
"www.wikipedia.org/wiki/")

And when people link a site, the benefits acrue to the site.

If I'm at a party and someone asked me about some pictures I took, I can
just tell them to go to:

	http://www.flickr.com/photos/mikeschinkel

My earlier albums on Snapfish.com, which are only visible if I send and
invite, have a URL like this to access (WTF?!?):

	
http://www1.snapfish.co.uk/share/p=12481168315141016/l=238932350/g=25011088/
cobrandOid=1007/otsc=SYE/otsi=SALB

I share an appreciation for motorcycles with my dad.  I like to send him
links in email. Let's assume the link breaks. Which one is he likely to be
able to fix? (and which one is least likely to break?)

	http://www.suzukicycles.com/Products/DRZ400SMK7/
	http://www.kawasaki.com/Products/Detail.aspx?id=201
	http://www.yamaha-motor.com/sport/products/modelhome/180/0/home.aspx
	
http://powersports.honda.com/motorcycles/sport/model.asp?ModelName=RC51&Mode
lYear=2006&ModelId=RVT1000R6


But if they were this instead this, it would be much easier for dad to
identify and fix those broken links (and much less likely they'd break):

	http://www.suzukicycles.com/bikes/drz400sm/2007/
	http://www.kawasaki.com/bikes/ninja-650r/2007/
	http://www.yamaha-motor.com/bikes/fjr12300a/2007/
	http://powersports.honda.com/bikes/rc51/2006/

Now, let's say that I wanted to send him a link to look at the 50th
Anniversary Sportster. See the link below? Tell me what I should send him.
Go head. Open it up. And tell me what link.

	
http://www.harley-davidson.com/wcm/Content/Pages/2007_Motorcycles/2007_Motor
cycles.jsp?locale=en_US&bmLocale=en_US

Now what if I wrote a blog article about that same motorcycle; what would I
link to?  (Well, it's okay, I'd never send dad a link to a Harley or blog
about one either. ;-)

So you see, there as so many small reasons why well designed URLs are a
benefit. But if you don't drill down to see those ways, it doesn't seem like
much at 50,000 feet.

> Meanwhile, URIs are supposed to be opaque from the client 
> angle, and it should by hypertext that is guiding them along 
> the path from one resource to the next.  Have you read up 
> much on these concepts?

Funny you should mention the URI Opacity Axiom[1]. Over the past 3-4 months,
I've probably read at least the first 100 references returned by googling
"uri opacity."  At this point, I'm going to go out an a limb and say I've
got a really good grasp of that ole' uri opacity axiom.  What's more, I've
very closely followed the metaDataInURIs[2] finding by TAG (have you read
that one?)

What all this research has told me is the vast majority of people
misinterpret the URI Opacity axiom, attempt to apply it far more broadly
than it was ever intended to be applied, and do so with such a zeal that I
wonder why this false doctrine has so excited their imaginations.  And I
don't say it's been misinterpreted because "I interpreted it correctly when
others failed."  No, I'm not that arrogant. I say it because I've seen
specific and explicit guidance given by TimBL and RoyTF on mailing list
discussions I've found during my research clarifying the issue.

In a nutshell, it goes like this:

1.) A URI should be considered opaque by a client if the URI authority
(server) has given it no explicit guidance.

2.) The URI authority (server) need not treat it's URLs as opaque; indeed a
server SHOULD organize its URLs logically and understandably to humans.

3.) In the case of a URL, the only part that needs to be considered opaque
is the path because the rest is specified (okay, an uninformed client shant
look at domains names like looking at "en.wikipedia.org" and guessing it is
English and hence de.wikipedia.org would be German.)

4.) HOWEVER, a URI authority (server) is free to provide explicit guidance
to a client and which point the client is free to treat the URIs as
transparent.

5.) Further, the URI Opacity concern is related to *machines*, not humans
because humans have an error correcting mechanism called intelligence.  If
they go to the "/cart/" URL and it displays information about wheelbarrows
instead of a shopping cart, the human can figure it out and continue
looking. The machine is yet to be capable until programmed in advance for
that problem.

So, nothing in my prior examples violates the URI Opacity Axiom[1] in any
way.  My examples actually follows the TAG finding[2] section "2.5: URIs
that are convenient for people to use", empowers "2.2: Guessing information
from a URI", and leverages "2.4: Authority use of URI metadata."

Ironically, cleaner and more obvious URLs are more likely to be transcribed
consistently then URLs with lots of query parameters that are 2 to 3 times
as long and almost impossible for non-programmers to read. In this way these
clean URLs improve cache efficiency.

Because URI Opacity is so misinterpreted and for some reason has been
misrepresented with such a passion, I plan to write a much longer blog
article on the subject once I'm able to gather all my research (probably 2-3
months from now.)

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://www.w3.org/DesignIssues/Axioms.html#opaque
[2] http://www.w3.org/2001/tag/doc/metaDataInURI-31

Walden Mathews wrote:
> : But in a nutshell, for the one example the benefits are URL 
> structure that
> : models the website's structure and contributing to a more 
> usable website and
> : more directly usable URL structure.
> 
> It's not clear who reaps these "benefits".  But I think you 
> are trying to design a web in which clients learn you rules 
> of hierarchy and then navigate your site by synthesizing 
> URL's by following the rules.
> 
> Meanwhile, URIs are supposed to be opaque from the client 
> angle, and it should by hypertext that is guiding them along 
> the path from one resource to the next.  Have you read up 
> much on these concepts?

Also, I just ran across this:
http://www.w3.org/QA/2004/08/readable-uri

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Chuck Hinson wrote:
> And if I understand Roy[1] correctly, the only constraint is that
> agents should not INFER properties from the URI.  As long as things
> are explicitly defined (by spec, by the server, or otherwise), agents
> can and do make use of information embedded in the URI.

That's problematic if the place it is explicitly defined is somewhere 
other than the hypermedia the client has received.

That said, I see nothing wrong in making guesswork on the part of a user 
more likely to work as they expect. Guesswork is a way that humans will 
always try to explore something and it's good UI to react to such 
guesses in a way they would expect.

It's a foolish user though that can't tell the difference between a 
guess they tried and "the way things are meant to be".

Mike Schinkel wrote:
> Well, I want to explore why it is harder for search engines to find that
> page. And can we change that?  Or consider the problem from a different
> perspective?

This is simple. The search engine finds x pages which it deems equally 
good as a response to a given query. Which does it link to first? 
There's no way of saying.

> Google tweaks their algorithms quarterly.  Why could they not
> include an update given new guidance?  The rest would follow.

We can already give this guidance to Google. Google reacts appropriately 
when it receives a 301 Moved Permanently by treating the target of the 
location header as the URI to use.

>> It is also a caching minus, because the cache 
>> won't know it already has something that came via a different 
>> URI. That can be a usability minus in the form of slower 
>> perceived response time, and a business minus in terms of 
>> higher bandwidth costs. 
> 
> Again, I'd like to explore why that is and see if there are not new ways to
> look at the problem.

The same reason you don't know whether what's behind door number 1 is 
the same as what's behind door number 2.

Again, but a note behind door number 2 saying "go to door number 1 and 
open that instead" and your problem is solved. As a bonus we can also 
control how often we check door number 2 to see if that note is still there.

Mike Schinkel wrote:
> Also, I just ran across this:
> http://www.w3.org/QA/2004/08/readable-uri


Being treated as opaque does not mean it can't be readable or respond 
well to guesswork.

Mike Schinkel wrote:
> For one example, look at Wikipedia's URLs; is it a wonder there are linked
> as often at they are? 
> 
> 	http://en.wikipedia.org/wiki/REST
> 
> IF it were instead
> 
> 	
> http://www.wikipedia.org/topic.php?topicID=7937521&lang=en-US&source-ie7&en-
> US&ie=utf8&oe=utf8
> 
> I can guarantee you it would not be linked as much.

If one 301'd to the other then the benefits you suggest are there would 
still hold.

> And when people link a site, the benefits acrue to the site.

There are more benefits in people linking to one page on your site than 
15 equivalent pages.

> So you see, there as so many small reasons why well designed URLs are a
> benefit. But if you don't drill down to see those ways, it doesn't seem like
> much at 50,000 feet.

The benefits of well-designed URIs is a different matter to the benefits 
of canonical URIs. Indeed one reason for having canonical URIs is to 
merge the benefits of a well-designed URI and a URI whose structure is 
forced upon you by other criteria or artefacts of implementation by 
having one permanently redirect to the canonical one.

> 5.) Further, the URI Opacity concern is related to *machines*, not humans
> because humans have an error correcting mechanism called intelligence.  If
> they go to the "/cart/" URL and it displays information about wheelbarrows
> instead of a shopping cart, the human can figure it out and continue
> looking. The machine is yet to be capable until programmed in advance for
> that problem.

No, the opacity concern is related to humans because if they phone and 
complain that they got information about wheelbarrows when they should 
have gotten a shopping cart I'm going to want to hit someone (not 
really, I get far worse calls than that, but they do make me want to hit 
someone). This is because humans have an error-generating mechanism 
called stupidity.

Responding reasonably to guesswork is great. I strive to design URI 
schemes as intuitively as I can. But I will delete any bug report about 
guessed URIs not working unless its very definitely marked as a 
suggested enhancement.

How should I model methods of resources, that not only change their
properties, but also create a process of some sort. For example, say I
have an application to manage the construction of buildings. Given a
building plan, I can instruct it to 'build()' the building. This will
cause the server to interact with other systems to purchase materials,
set up tasks for employees etc.

Should I use 'POST' with a 'method=build' parameter to the 'plan' URI?

Thanks,
Ittay

Hi Ittay,
 
the kind of question you ask indicates that you have no yet understood a fundamental aspect of REST, namely that there is a uniform interface. You do not get any other methods as the uniform set (the HTTP methods in the case of using HTTP as an architecture)

Without any intention to be rude, I suggest you take a while to read through some of the REST material out on the Web (the REST wiki at http://rest.blueoxen.net is a good starting point as is Paul's site at http://prescod.com/rest ). This will help in future discussions.


>Should I use 'POST' with a 'method=build' parameter to the 'plan' URI?

No, this is about the worst from a REST POV as it is hidden RPC.

Think along these lines:

Provide a means for clients to pick a resource that behaves the way they are interested in (some hypermedia the clients come accross could declare a resource as a BuildingManager) and then use POST to submit the building plan.

POST /BuildingManager
Content-Type: application/blueprint          <-- this type is fictous; it would need to be standardized within the realm of your system

<blueprint>
  <wall location="...."/>
</blueprint>


IOW, in a RESTful system clients late-bind to resources based on runtime-declared abstract bahavior of those resources and they communicate via a fixed set of methods.

HTH,

Jan 





>Thanks,
>Ittay
>
>
>
> 
>Yahoo! Groups Links
>
>
>
>
>

thanks for your example and site reference.

i did know that i use only HTTP methods, what i lacked is how to model my business methods. i am a newbie at this (maybe i should have indicated that)

may i impose with a followup?

say i have a person entity in my application. this entity has several business methods (eat, sleep, work). how should i model a rest api for these? create a PersonManager resource (which then will need to accept as argument what action to do), or create resources per action (/person/ittay/eat maybe?). 

thanks,
ittay

Jan Algermissen wrote:
> Hi Ittay,
>  
> the kind of question you ask indicates that you have no yet understood a fundamental aspect of REST, namely that there is a uniform interface. You do not get any other methods as the uniform set (the HTTP methods in the case of using HTTP as an architecture)
> 
> Without any intention to be rude, I suggest you take a while to read through some of the REST material out on the Web (the REST wiki at http://rest.blueoxen.net is a good starting point as is Paul's site at http://prescod.com/rest ). This will help in future discussions.
> 
> 
>> Should I use 'POST' with a 'method=build' parameter to the 'plan' URI?
> 
> No, this is about the worst from a REST POV as it is hidden RPC.
> 
> Think along these lines:
> 
> Provide a means for clients to pick a resource that behaves the way they are interested in (some hypermedia the clients come accross could declare a resource as a BuildingManager) and then use POST to submit the building plan.
> 
> POST /BuildingManager
> Content-Type: application/blueprint          <-- this type is fictous; it would need to be standardized within the realm of your system
> 
> <blueprint>
>   <wall location="...."/>
> </blueprint>
> 
> 
> IOW, in a RESTful system clients late-bind to resources based on runtime-declared abstract bahavior of those resources and they communicate via a fixed set of methods.
> 
> HTH,
> 
> Jan 
> 
> 
> 
> 
> 
>> Thanks,
>> Ittay
>>
>>
>>
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>>
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

: Hmm. You're right that that document defines agents as both software  
: and people, but I suspect most web users haven't read that document  
: and may not know to not infer anything from URIs. My belief is that  
: people do use the URI for clues as to information architecture, and  
: therefore I think it is appropriate to design URIs with that in mind.

Present the "information architecture" through hypertext instead.

Benefits:

1. You train your user to use the system at full leverage.

2. You retain encapsulation of your implementation, and are
     then free to change it without breaking your clients.

: Mike can do that too, but all those things need to be at some URI  
: each, so why not select a canonical URI for each resource that may  
: help users figure out where they are in his information architecture.  
: Users aren't depending on a URI meaning what they guess it means.  
: They just try it and see if the representation matched their  
: expectations. If it doesn't, they will quickly try something else. It  
: is the representation that they ultimately depend on.

What do we mean by "canonical" here?  I thought, in this context,
it only meant "authorized", as in "which URL to redirect an alias to".

Walden

:
: For one example, look at Wikipedia's URLs; is it a wonder there are linked
: as often at they are?
:
: http://en.wikipedia.org/wiki/REST
:
: IF it were instead
:
: 
http://www.wikipedia.org/topic.php?topicID=7937521&lang=en-US&source-ie7&en-
: US&ie=utf8&oe=utf8
:
: I can guarantee you it would not be linked as much.  I could remember and
: compose the former, there is no way I could remember the latter (FYI, I
: frequently like to Wikipedia just by prefixing a term with
: "www.wikipedia.org/wiki/")

1. I can tell you are in sales.
2. You make assumptions I don't: have you heard of cut and paste?

: If I'm at a party and someone asked me about some pictures I took, I can
: just tell them to go to:
:
: http://www.flickr.com/photos/mikeschinkel
:

I guess if they can remember that, several hours and several beers
later, then they can probably also remember your name.  That's
better than I can do.

Typically, I email or IM links to people.  As far as typing into the
location bar of the browser, I avoid it like the plague.

: I share an appreciation for motorcycles with my dad.  I like to send him
: links in email. Let's assume the link breaks. Which one is he likely to be
: able to fix? (and which one is least likely to break?)

Breaks?  You mean line breaks?  Yes, I agree with *short* URI
in principle.

: But if they were this instead this, it would be much easier for dad to
: identify and fix those broken links (and much less likely they'd break):

I feel bad for your dad in this case, and if I were he, I'd stick to
fixing motorcycles, because it would entail much less futile typing.

Honestly, Mike, show your dad how to cut and paste broken (line
wrapped) URI back together.  As for other breakage, forget it.
:
: http://www.suzukicycles.com/bikes/drz400sm/2007/
: http://www.kawasaki.com/bikes/ninja-650r/2007/
: http://www.yamaha-motor.com/bikes/fjr12300a/2007/
: http://powersports.honda.com/bikes/rc51/2006/
:
: Now, let's say that I wanted to send him a link to look at the 50th
: Anniversary Sportster. See the link below? Tell me what I should send him.
: Go head. Open it up. And tell me what link.

I'm afraid....


Walden 

Hmmm. I'm a bit of a newbie too but let me take a stab at this as an
exercise. 

Now let me first say that the way you posed the question is very
"objecty" or "servicey" to begin with and makes it a bit hard to
answer. You've basically said "I have a service with methods A, B, and
C; how do I make it resource based?" The problem is that REST has no
concept of class-specific methods, so without knowing what A, B, and C
do, its hard to answer your question. In short, there is no straight
forward transformation of an abstract service to abstract resources.
(At least not that I know of...) They are two very different ways of
modeling the interface. I can't transform one type of solution to
another without understanding the problem.

But I can infer a bit about the problem from the fact you are using
the concept of a person and things a person can do (eat, sleep, work).
I'll assume here that sleep() and work() change the state of the
person (to sleeping and working respectively). Maybe there is a
substate when working that says what work you are doing. Let's also
assume that eat() adds some food items to a list of things eaten.

So to work (on building a bike shed):
PUT /person/ittay/currentactivity
Content-Type: application/x-activity+xml

<activity>
  <type>work</type>
  <sub-type>building a bike shed</sub-type>
</activity>

To sleep:
PUT /person/ittay/currentactivity
Content-Type: application/x-activity+xml

<activity>
  <type>sleep</type>
</activity>

To eat an apple:
POST /person/ittay/stomach
Content-type: application/x-food+xml

<food>apple</food>

Now these actions could also kick off related business processes. I
think the only method that can't is GET. Note that you could use get
to retrieve the current activity from /person/ittay/currentactivity or
the list of things eaten from /person/ittay/stomach.


--- In rest-discuss@yahoogroups.com, Ittay Dror <ittayd@...> wrote:
>
> thanks for your example and site reference.
> 
> i did know that i use only HTTP methods, what i lacked is how to
model my business methods. i am a newbie at this (maybe i should have
indicated that)
> 
> may i impose with a followup?
> 
> say i have a person entity in my application. this entity has
several business methods (eat, sleep, work). how should i model a rest
api for these? create a PersonManager resource (which then will need
to accept as argument what action to do), or create resources per
action (/person/ittay/eat maybe?). 
> 
> thanks,
> ittay
> 
> Jan Algermissen wrote:
> > Hi Ittay,
> >  
> > the kind of question you ask indicates that you have no yet
understood a fundamental aspect of REST, namely that there is a
uniform interface. You do not get any other methods as the uniform set
(the HTTP methods in the case of using HTTP as an architecture)
> > 
> > Without any intention to be rude, I suggest you take a while to
read through some of the REST material out on the Web (the REST wiki
at http://rest.blueoxen.net is a good starting point as is Paul's site
at http://prescod.com/rest ). This will help in future discussions.
> > 
> > 
> >> Should I use 'POST' with a 'method=build' parameter to the 'plan'
URI?
> > 
> > No, this is about the worst from a REST POV as it is hidden RPC.
> > 
> > Think along these lines:
> > 
> > Provide a means for clients to pick a resource that behaves the
way they are interested in (some hypermedia the clients come accross
could declare a resource as a BuildingManager) and then use POST to
submit the building plan.
> > 
> > POST /BuildingManager
> > Content-Type: application/blueprint          <-- this type is
fictous; it would need to be standardized within the realm of your system
> > 
> > <blueprint>
> >   <wall location="...."/>
> > </blueprint>
> > 
> > 
> > IOW, in a RESTful system clients late-bind to resources based on
runtime-declared abstract bahavior of those resources and they
communicate via a fixed set of methods.
> > 
> > HTH,
> > 
> > Jan 
> > 
> > 
> > 
> > 
> > 
> >> Thanks,
> >> Ittay
> >>
> >>
> >>
> >>
> >> Yahoo! Groups Links
> >>
> >>
> >>
> >>
> >>
> > 
> 
> 
> -- 
> ===================================
> Ittay Dror, 
> Chief architect, 
> R&D, Qlusters Inc.
> ittayd@...
> +972-3-6081994 Fax: +972-3-6081841
> 
> www.openqrm.org - Data Center Provisioning
>

Hi-

Been lurking for a while, but this is my first time posting a question
here, so forgive the newbieness of it. :)

I've seen a couple of different ways to link to resources but I
haven't seen a good argument for one way or another. Are any of these
more correct than the other? Or is there some other better way?

<foos uri="http://api.example.com/foo/">
  <foo uri="http://api.example.com/foo/1">
    <short_description>Foo 1</short_description>
  </foo>
  <foo uri="http://api.example.com/foo/2">
    <short_description>Foo 2</short_description>
  </foo>
  <foo uri="http://api.example.com/foo/3">
    <short_description>Foo 3</short_description>
  </foo>
</foos>

<foos href="http://api.example.com/foo/">
  <foo href="http://api.example.com/foo/1">
    <short_description>Foo 1</short_description>
  </foo>
  <foo href="http://api.example.com/foo/2">
    <short_description>Foo 2</short_description>
  </foo>
  <foo href="http://api.example.com/foo/3">
    <short_description>Foo 3</short_description>
  </foo>
</foos>

<foos xlink:type"simple" xlink:href="http://api.example.com/foo/">
  <foo xlink:type"simple" xlink:href="http://api.example.com/foo/1">
    <short_description>Foo 1</short_description>
  </foo>
  <foo xlink:type"simple" xlink:href="http://api.example.com/foo/2">
    <short_description>Foo 2</short_description>
  </foo>
  <foo xlink:type"simple" xlink:href="http://api.example.com/foo/3">
    <short_description>Foo 3</short_description>
  </foo>
</foos>

Cheers,
Michael

Hi Walden,

On Jan 9, 2007, at 7:51 AM, Walden Mathews wrote:

> : Hmm. You're right that that document defines agents as both software
> : and people, but I suspect most web users haven't read that document
> : and may not know to not infer anything from URIs. My belief is that
> : people do use the URI for clues as to information architecture, and
> : therefore I think it is appropriate to design URIs with that in  
> mind.
>
> Present the "information architecture" through hypertext instead.
>
A agree he should present the information architecture through  
hypertext, but it need not be "instead." It can be in addition to  
presenting it in the URI. Like it or not, both the hypertext and the  
URI are part of the user interface of a web application.

> Benefits:
>
> 1. You train your user to use the system at full leverage.
>
What do you mean by "full leverage?"

> 2. You retain encapsulation of your implementation, and are
>      then free to change it without breaking your clients.
>
I'm not sure what you mean by this either. I'm recommending URI  
design from a user perspective, not from the perspective of what  
makes it easy to implement. Thus changing the implementation does not  
imply changing the URI.

> : Mike can do that too, but all those things need to be at some URI
> : each, so why not select a canonical URI for each resource that may
> : help users figure out where they are in his information  
> architecture.
> : Users aren't depending on a URI meaning what they guess it means.
> : They just try it and see if the representation matched their
> : expectations. If it doesn't, they will quickly try something  
> else. It
> : is the representation that they ultimately depend on.
>
> What do we mean by "canonical" here?  I thought, in this context,
> it only meant "authorized", as in "which URL to redirect an alias to".
>
Yes, that's what I mean by canonical. A canonical form, to which  
other URIs that may mean the same thing redirect to. In my case, the  
reason I had multiple URIs referring to the same resource anyway was  
that by default that's what Java Servlets gave me.

Speaking of servlets, last night I tried canonicalizing away a  
trailing question mark, and discovered that there's now way to detect  
that situation with the servlet API. I wanted to transform:

http://www.artima.com/articles?

Into:

http://www.artima.com/articles

But unfortunately I can't. Search engines  might infer that these are  
the same, and canonicalize this themselves. By the "rules," of  
course, they shouldn't. They should treat these URIs opaquely, and  
since they are different, not infer that one means the other. But if  
in 99.9% of the cases out there this means the same thing, and  
therefore this inferring allows the search engine to give better  
results to their users, they just might do it. Search engines must  
design for reality, and should web app designers. In reality, users  
do look to the URI for hints at the information architecture.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

what troubles me is that most examples i find to explain rest use simple cases, where no logic is actually running, and so it is easy to transfer services to properties (since the services do very little)

so here is my real world use case: openQRM is a platform for provisioning and managing services in a DC. a service is an entity named VirtualEnvironment that encapsulates both a set of policies on how to provision and manage the real service and a capture of the real service's state (resources, utilization, error, etc.)

we can do many actions on a service, but the primary ones are to start and stop it. starting means resources are selected from a pool and assigned to work for the service, the software is deployed on them and the service is monitored. stopping is the reverse. obviously openQRM does all this. the client just requests to 'start' or 'stop'.

now, it is hard for me to see 'start' and 'stop' as values of the 'currentactivity' property. if anything, it looks like a masquerade of the RPC equivalent of posting to the VirtualEnvironment entity with the pair 'action=start'. 

thank you for your help,
ittay

wahbedahbe wrote:
> 
> 
> Hmmm. I'm a bit of a newbie too but let me take a stab at this as an
> exercise.
> 
> Now let me first say that the way you posed the question is very
> "objecty" or "servicey" to begin with and makes it a bit hard to
> answer. You've basically said "I have a service with methods A, B, and
> C; how do I make it resource based?" The problem is that REST has no
> concept of class-specific methods, so without knowing what A, B, and C
> do, its hard to answer your question. In short, there is no straight
> forward transformation of an abstract service to abstract resources.
> (At least not that I know of...) They are two very different ways of
> modeling the interface. I can't transform one type of solution to
> another without understanding the problem.
> 
> But I can infer a bit about the problem from the fact you are using
> the concept of a person and things a person can do (eat, sleep, work).
> I'll assume here that sleep() and work() change the state of the
> person (to sleeping and working respectively) . Maybe there is a
> substate when working that says what work you are doing. Let's also
> assume that eat() adds some food items to a list of things eaten.
> 
> So to work (on building a bike shed):
> PUT /person/ittay/ currentactivity
> Content-Type: application/ x-activity+ xml
> 
> <activity>
> <type>work</ type>
> <sub-type>building a bike shed</sub-type>
> </activity>
> 
> To sleep:
> PUT /person/ittay/ currentactivity
> Content-Type: application/ x-activity+ xml
> 
> <activity>
> <type>sleep< /type>
> </activity>
> 
> To eat an apple:
> POST /person/ittay/ stomach
> Content-type: application/ x-food+xml
> 
> <food>apple< /food>
> 
> Now these actions could also kick off related business processes. I
> think the only method that can't is GET. Note that you could use get
> to retrieve the current activity from /person/ittay/ currentactivity or
> the list of things eaten from /person/ittay/ stomach.
> 
> --- In rest-discuss@ yahoogroups. com 
> <mailto:rest-discuss%40yahoogroups.com>, Ittay Dror <ittayd@...> wrote:
>  >
>  > thanks for your example and site reference.
>  >
>  > i did know that i use only HTTP methods, what i lacked is how to
> model my business methods. i am a newbie at this (maybe i should have
> indicated that)
>  >
>  > may i impose with a followup?
>  >
>  > say i have a person entity in my application. this entity has
> several business methods (eat, sleep, work). how should i model a rest
> api for these? create a PersonManager resource (which then will need
> to accept as argument what action to do), or create resources per
> action (/person/ittay/ eat maybe?).
>  >
>  > thanks,
>  > ittay
>  >
>  > Jan Algermissen wrote:
>  > > Hi Ittay,
>  > >
>  > > the kind of question you ask indicates that you have no yet
> understood a fundamental aspect of REST, namely that there is a
> uniform interface. You do not get any other methods as the uniform set
> (the HTTP methods in the case of using HTTP as an architecture)
>  > >
>  > > Without any intention to be rude, I suggest you take a while to
> read through some of the REST material out on the Web (the REST wiki
> at http://rest. blueoxen. net <http://rest.blueoxen.net> is a good 
> starting point as is Paul's site
> at http://prescod. com/rest <http://prescod.com/rest> ). This will help 
> in future discussions.
>  > >
>  > >
>  > >> Should I use 'POST' with a 'method=build' parameter to the 'plan'
> URI?
>  > >
>  > > No, this is about the worst from a REST POV as it is hidden RPC.
>  > >
>  > > Think along these lines:
>  > >
>  > > Provide a means for clients to pick a resource that behaves the
> way they are interested in (some hypermedia the clients come accross
> could declare a resource as a BuildingManager) and then use POST to
> submit the building plan.
>  > >
>  > > POST /BuildingManager
>  > > Content-Type: application/ blueprint <-- this type is
> fictous; it would need to be standardized within the realm of your system
>  > >
>  > > <blueprint>
>  > > <wall location=".. .."/>
>  > > </blueprint>
>  > >
>  > >
>  > > IOW, in a RESTful system clients late-bind to resources based on
> runtime-declared abstract bahavior of those resources and they
> communicate via a fixed set of methods.
>  > >
>  > > HTH,
>  > >
>  > > Jan
>  > >
>  > >
>  > >
>  > >
>  > >
>  > >> Thanks,
>  > >> Ittay
>  > >>
>  > >>
>  > >>
>  > >>
>  > >> Yahoo! Groups Links
>  > >>
>  > >>
>  > >>
>  > >>
>  > >>
>  > >
>  >
>  >
>  > --
>  > ============ ========= ========= =====
>  > Ittay Dror,
>  > Chief architect,
>  > R&D, Qlusters Inc.
>  > ittayd@...
>  > +972-3-6081994 Fax: +972-3-6081841
>  >
>  > www.openqrm. org - Data Center Provisioning
>  >
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

On Tue, 2007-01-09 at 16:35 +0000, mmakunas wrote:
> I've seen a couple of different ways to link to resources but I
> haven't seen a good argument for one way or another. Are any of these
> more correct than the other? Or is there some other better way?

So, "@uri vs. @href", and separately, "using xlink".

I don't think it matters.

I'm not sure anyone is using xlink, though you might want to adopt it if
you think its model makes sense for your app, and it won't put off
consumers of your resources.  The idea of a processing handling xlink'ed
values without understanding the "containing" document itself doesn't
really seem to work.

W.r.t @uri vs. @href (vs. @src, vs. @rdf:about, ...), I'd say: be
consistent; I'm not sure there's any generic tooling our there that
would leverage using one over the other.

-- 
...jsled
http://asynchronous.org/ - a=jsled;b=asynchronous.org;echo ${a}@${b}

Ittay,

On Tue, 2007-01-09 at 22:39 +0200, Ittay Dror wrote:
> what troubles me is that most examples i find to explain rest use
> simple cases, where no logic is actually running, and so it is easy to
> transfer services to properties (since the services do very little)
> so here is my real world use case: openQRM is a platform for
> provisioning and managing services in a DC. a service is an entity
> named VirtualEnvironment that encapsulates both a set of policies on
> how to provision and manage the real service and a capture of the real
> service's state (resources, utilization, error, etc.)
> we can do many actions on a service, but the primary ones are to start
> and stop it. starting means resources are selected from a pool and
> assigned to work for the service, the software is deployed on them and
> the service is monitored. stopping is the reverse. obviously openQRM
> does all this. the client just requests to 'start' or 'stop'.

I think the way to look at it is from the other direction. All
communication involves the transfer of information. The HTTP verbs put
this feature of the communication front and centre by collapsing all of
the possible methods in the world down to a small set that transfer
information. Instead of saying {theService, "startService"}, we say
{"http://example.com/services/theService/running", "PUT", text/plain
"true"}. This message contains the same information, but puts the
request into a canonical form. It uses a standard method to transfer the
state and a standard content type to format the information.

Using standard methods and content types has architectural implications
that are not obvious when you write a single server or client/server
pair. Consider the possibility that the author of the client doesn't
want to write software just for your service. Consider the possibility
that they want it to work for a thousand service providers. By phrasing
the request in terms of standard methods and content types we increase
the likelyhood that the request will be understood by many service
providers.

Once I have written a client that works with your service, I can make it
work with other services just by providing a different url. In fact,
depending on the semantics of my client I could even point it at
completely different kinds of functions. I could turn a lightbulb on and
off. I could interact with a building automation system.

Using standard methods and content types also assits intermediataries
such as proxies in determining how to handle requests correctly. For
example, I might bar all PUT access to http://example.com/services not
owned by the user... but might still allow GET access or might allow GET
access to a different class of user. If we were not using standard
methods or if we were hiding actions away in urls it would be more
difficult to craft these kinds of rules.

Benjamin

Hi Roy,

On Jan 4, 2007, at 5:37 PM, Roy T. Fielding wrote:

>> http://www.artima.com/articles?o=a&t=java&p=4
>
> Why don't you redirect to a permalink style URI?  The ? will reduce
> your cache effectiveness, and is mighty ugly.  Well, I guess for
> "give me a list of java articles sorted by title" that is okay,
> since the articles themselves seem to have permalinks.  Note that
>
>    http://www.artima.com/articles/java/index;date;p4
>
> is short and says more.  YMMV.
>
I wanted to verify that I'm correctly reading 3.3. Path Component  
from the URI Generic Syntax doc:

http://www.ietf.org/rfc/rfc2396.txt

Basically in the path portion of a URI you can have a set of params  
at the end of a segment, each prepended by a ; char. And it is OK to  
have a ; char at the end. So these would be valid:

http://www.artima.com/articles;oa;tjava;p5
http://www.artima.com/articles;p5
http://www.artima.com/articles

And also:

http://www.artima.com/articles;oa;tjava;p5;
http://www.artima.com/articles;p5;
http://www.artima.com/articles;

Has anyone had any troubles in practice using URIs with params in  
their segments? Are people moving towards this approach rather than  
query parameters with their ?, &, and = chars?

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Jan 9, 2007, at 3:56 PM, Bill Venners wrote:
> I wanted to verify that I'm correctly reading 3.3. Path Component  
> from the URI Generic Syntax doc:
>
> http://www.ietf.org/rfc/rfc2396.txt

Toss it... you should be looking at

  http://www.ietf.org/rfc/rfc3986.txt


> Basically in the path portion of a URI you can have a set of params  
> at the end of a segment, each prepended by a ; char. And it is OK  
> to have a ; char at the end. So these would be valid:
>
> http://www.artima.com/articles;oa;tjava;p5
> http://www.artima.com/articles;p5
> http://www.artima.com/articles
>
> And also:
>
> http://www.artima.com/articles;oa;tjava;p5;
> http://www.artima.com/articles;p5;
> http://www.artima.com/articles;
>
> Has anyone had any troubles in practice using URIs with params in  
> their segments?

Not that I know of.

> Are people moving towards this approach rather than query  
> parameters with their ?, &, and = chars?

A few, but only when they are not using HTML forms to create the query.
The vast majority just copy whatever they read in "CGI for Dummies".
The only real difference is that some app frameworks will pre-parse
the ?key=value args for you, so it is simpler to implement.

It used to be that browsers and Squid would not cache any response
containing a query segment, but that may have changed by now.

....Roy

[ Attachment content not displayed ]

Bill Venners <bv-svp@...> writes:

> Basically in the path portion of a URI you can have a set of params  
> at the end of a segment, each prepended by a ; char. And it is OK to  
> have a ; char at the end. So these would be valid:
>
> http://www.artima.com/articles;oa;tjava;p5
> http://www.artima.com/articles;p5
> http://www.artima.com/articles
>
> And also:
>
> http://www.artima.com/articles;oa;tjava;p5;
> http://www.artima.com/articles;p5;
> http://www.artima.com/articles;

But also:

  http://www.artima.com/articles;p1=1;/java;p2=3
  http://www.artima.com/articles;p1=hello;p2=world/java/serverside;p4=xxx

I once tried to get the servlet API expert group to understand this
but at the time they didn't really get it.


> Has anyone had any troubles in practice using URIs with params in  
> their segments? Are people moving towards this approach rather than  
> query parameters with their ?, &, and = chars?

It would be good because it is so much more flexible. However, it is
also really complicated to parse or represent.

Personally, I stick with a path and then a query.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Hi Hugh,

On Jan 9, 2007, at 4:21 PM, Hugh Winkler wrote:

> On 1/9/07, Bill Venners <bv-svp@...> wrote:\
>
>> Has anyone had any troubles in practice using URIs with params in
>> their segments?
>
> Yes. Tomcat strips everything after the first semicolon before passing
> the uri to the servlet, because that's where they stuff their stupid
> ;JSESSIONID=.... when they can't use cookies.
>
Oh brother. Well that's a problem. About the only thing I use from  
J2EE right now in our new architecture is the parsing of query  
params. I was frustrated a few months ago when I wanted to figure out  
a way to custom encode a session ID into a URL. The spec doesn't  
allow for that as far as I could see. Yesterday I discovered the API  
doesn't allow me to canonicalize away a lone question mark at the end  
of a URI. I was thinking of switching from Tomcat to JETTY, so  
perhaps that will preserve the ; params.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On 1/9/07, Bill Venners <bv-svp@...> wrote:\

> Has anyone had any troubles in practice using URIs with params in
> their segments?

Yes. Tomcat strips everything after the first semicolon before passing
the uri to the servlet, because that's where they stuff their stupid
;JSESSIONID=.... when they can't use cookies.


Hugh

Bill Venners <bv-svp@...> writes:

> Oh brother. Well that's a problem. 

segment params were discussed for 2.4 Servlet API. As I recall people
wanted to treat them as parameters (ie: the same as POST/form-data or
query parameters).

But you can't do that coz they're more complicated than that.


> About the only thing I use from  
> J2EE right now in our new architecture is the parsing of query  
> params. I was frustrated a few months ago when I wanted to figure out  
> a way to custom encode a session ID into a URL. The spec doesn't  
> allow for that as far as I could see. 

Declare a filter that provides the getSession() method to the
downstream targets.

You'd have to use your own session implementation of course.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Jan 9, 2007, at 4:21 PM, Hugh Winkler wrote:
> Yes. Tomcat strips everything after the first semicolon before passing
> the uri to the servlet, because that's where they stuff their stupid
> ;JSESSIONID=.... when they can't use cookies.

Crikey... why doesn't someone just fix the code?  I mean, that
is too broken for words -- if I did that in Apache httpd the users
would lynch me (assuming it ever got past the dev list).

....Roy

Hi Nic,

On Jan 9, 2007, at 4:13 PM, Nic James Ferrier wrote:

> But also:
>
>   http://www.artima.com/articles;p1=1;/java;p2=3
>   http://www.artima.com/articles;p1=hello;p2=world/java/ 
> serverside;p4=xxx
>
I think segments are offset by slashes, so if you want /java to be  
a ; param you'd probably need to encode it as in:

http://www.artima.com/articles;p1=1;%2Fjava;p2=3

Otherwise a relative link on that page of "fred.html" will attempt to  
be grabbed from:

http://www.artima.com/articles;p1=1;/fred.html

(I think.)

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Bill Venners <bv-svp@...> writes:

> Hi Nic,
>
> On Jan 9, 2007, at 4:13 PM, Nic James Ferrier wrote:
>
>> But also:
>>
>>   http://www.artima.com/articles;p1=1;/java;p2=3
>>   http://www.artima.com/articles;p1=hello;p2=world/java/ 
>> serverside;p4=xxx
>>
> I think segments are offset by slashes, so if you want /java to be  
> a ; param you'd probably need to encode it as in:
>
> http://www.artima.com/articles;p1=1;%2Fjava;p2=3
>
> Otherwise a relative link on that page of "fred.html" will attempt to  
> be grabbed from:
>
> http://www.artima.com/articles;p1=1;/fred.html

You misunderstand my understanding of the spec   /8->

I was trying to say that I think that each segment can have parameters
associated with it, eg in the path:

   /articles;p1=hello;p2=world/java;p3=nice;p5=day

the segment "/articles" can have some parameters:

  p1=hello
  p2=world

and the segment "/java" can have some parameters:

  p4=nice
  p5=day


This certainly used to be the case. I'm not sure what the current
situation is.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Elliotte Harold wrote:
> Mike Schinkel wrote:
> 
> > The internal admins configuring the firewall in many places are 
> > clueless (believe me, I ran a business for a while where that was 
> > truly the case but I couldn't afford to hire anyone better. And it 
> > will be the case in many small to medium size businesses.)
> 
> The market will deal with businesses like that. 

I believe that the market doesn't care about that level of detail, only
academics and standard committees care to that extent. I believe the market
cares about what works for them to achieve their specific goals.

> I don't see why genuinely competent organizations should...

You are defining "genuinely competent organizations" using one measure;
their adherence to a technical ideal.  There are many other measures of a
competent organization, and the market views earnings of "for-profit"
companies as one of it's most important concerns. If following a certain
technical ideal depresses earnings then while you would view the
organization as genuinely competent there are a large group of others,
especially shareholders and most employees who would view the company as
grossly incompetent.

I don't mean to discredit your view; I instead mean to point out that they
are numerous views and that those views should be weighed and balanced
accordingly. Suggesting the other view is not important may make one feel
better, but it won't achieve any related improvements.

> have to put up with bad architectures to support their 
> pointy-haired competitors.

Aside from the unnecessary denigration which I will ignore, you may have
misunderstood; I didn't mean "support competitors", I meant "compete with
competitors."

> It seems suspicious to me that these purported admins who are 
> so incompetent they can't properly manage PUT and DELETE knew 
> enough to block these methods in the first place. I suspect 
> what may really be going on is unchanged defaults in the 
> firewalls and proxy servers. If indeed that's the case then 
> it's much easier to fix the problem at its source by 
> educating a relatively small number of proxy and firewall vendors.

I made an assumption in my comments which you ferreted out; that yes I was
talking about defaults where users of proxies and firewalls who barely have
the skills (or the money) to get them up and running, let alone optimize
them. With many organizations, even large one, use the same "Jell-O" model
[1] for infrastructure configuration as some companies use for shipping
software; when it stops quivering it's done!

OTOH, Nic was speaking about the large organizations where one departments
often didn't care about the concerns of others.

> Indeed all you may need to do when a customer tells you your 
> system seems broken is say, "Oh, you're using proxy X? That's 
> broken and non-spec compliant. Use proxy Y instead and all 
> will be fine."

That's fine, assuming that information gets to the right person in the
company (which is a huge assumption) and that the right person doesn't have
other tasks they view as higher priority (which is another big assumption.)

> Of course, this is not a binary situation. Some will fix 
> their systems and some won't. My experience leads me to 
> believe that when you insist on spec compliance, more people 
> will fix their systems and come into compliance than won't. 

I wouldn't disagree with this.

> You will lose a few percent. 

That, unfortunately, is the problem.  When you are in government or academia
you can usually afford to be draconian.  But in the business world that "few
percent" is often the difference between meeting quarterly goals or not. For
small companies it can be the difference between making payroll or not. I'm
well aware of the latter as I've been in the role of having to meet payroll
for more than 20 years of my career. I don't know your experience; have you?

A for-profit business cannot choose to enforce a standard on its customers
over achieving either of the aforementioned two things. Taking what many,
who are not technical, would view as an overly pedantic posture on standards
over meeting revenue projections would most certainly lead shareholders to
replacing management at best, or to suing them at worst.

> However if you try and support 
> all the broken and brain damaged networks out there, you do
>   far more damage to everyone. You end up hurting the 
> compliant customers to support the noncompliant ones in a 
> dozen different, subtle ways. Maximum net benefit to all 
> involved is achieved by jettisoning the truly incompetent 
> organizations that will not and cannot learn the proper way 
> to do things.

Unfortunately, only people who are drawn to the technology for personal
interest see this as important enough to allow it to affect other factors.
For another perspective on this, ask the WHATWG editor Ian Hickson if he
thinks browser vendors will support standards that could potentially
minimize their marketshare in any way.[2]  Almost no company will be willing
to limit it's marketshare for a technical ideal. The way to achieve the
technical ideal on as broad basis as possible is to make that support
painless, not by ignoring market realities with the claim that "it is the
right thing to do for the greater good." 

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://www.google.com/search?q="Don't+shake+the+Jell-O"
[2]
http://listserver.dreamhost.com/pipermail/whatwg-whatwg.org/2006-December/00
8600.html

Dr. Ernie Prabhakar wrote:
> I'm a static resource bigot

Me to. 

> > A. Static
> > http://www.foo.com/users/
> > http://www.foo.com/users/john-smith/
> > http://www.foo.com/users/john-smith/cell-phone/
> + shorter
> + implies fixed resources
> + implies a single unique resource
> 
> B. Dynamic (Long)
> > http://www.foo.com/?section=users
> > http://www.foo.com/?section=users&user=john-smith
> > http://www.foo.com/?section=users&user=john-smith&phone=cell-phone
> I actually think this is the wrong contrast. I would propose instead:
> 
> C. Dynamic (Short)
> > http://www.foo.com/?user=*
> > http://www.foo.com/?user=john-smith
> > http://www.foo.com/?user=john-smith&phone=cell-phone
> Since "section = users" seems redundant with "user=".
> 
> Given "A" and "C", I actually think which is better becomes 
> context- dependent. If you have static tree of resources the 
> end user drills down, then "A" is the most natural. If you 
> have a huge database where the user could be sorting on many 
> different fields, then "C" might be the simpler construction.

What specifically make C simplier in your view?  HTML FORMs support C better
than A, but I was explicitly asking about REST based systems which we all
know HTML FORMs do not well support.

Thanks for the comments.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Bill Venners wrote:
> If I understand this correctly, the term resource in the 
> REST and HTTP context means a thing of value as perceived 
> by the people using the  system. If all you have is a bunch 
> of URIs, you can't make any assumptions about whether 
> they refer to the same resource or not. But if you have a 
> bunch of URIs plus more semantic information about the 
> resources they represent, then you can make such 
> assumptions.

Yes, that's where my thoughts are headed..

--
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Mark Baker wrote:
> This is a FAQ, Mike.  I'm sure a search for "query" in the 
> archives will turn up a gold mine of pros/cons.

Oh, I'm well aware. I've got many printed pages from list discussions and
web articles on the subject. But I wanted to get people's direct opinions
because it is easier to get direct responses than to ferret out opinions
based from context when the discussion was on other topics.

> If you could put what you find on the RESTwiki (the FAQ 
> page  in particular), it would be appreciated.

I ultimately plan to blog about it, but could also reference it on the
RESTwiki.

However, the reason I was asking was because I was trying to gather evidence
to present to Ian Hickson to support adding URI Template support to the
action method of the form element in Web Forms 2.0.  I sent an email to
uri@... to that effect[1], but got to response.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

[1] http://lists.w3.org/Archives/Public/uri/2006Dec/0028.html

Caches ceased placing undue significance on the query string long ago.
IIRC, that behavior became obsolete as PHP became more popular.

Using query parameters in path segments is uninteresting. They make
ugly object references, and most civilized web software translates
human readable URLs to CGI environment variables using rewrite rules.
See Rails,  Python Routes/WSGI, and good old mod_rewrite. In theory,
structured path segments allow more versatile delegation of authority,
but it doesn't seem economically compelling so far.

-Rob

On 1/9/07, Roy T. Fielding <fielding@...> wrote:
> On Jan 9, 2007, at 3:56 PM, Bill Venners wrote:
> > I wanted to verify that I'm correctly reading 3.3. Path Component
> > from the URI Generic Syntax doc:
> >
> > http://www.ietf.org/rfc/rfc2396.txt
>
> Toss it... you should be looking at
>
>   http://www.ietf.org/rfc/rfc3986.txt
>
>
> > Basically in the path portion of a URI you can have a set of params
> > at the end of a segment, each prepended by a ; char. And it is OK
> > to have a ; char at the end. So these would be valid:
> >
> > http://www.artima.com/articles;oa;tjava;p5
> > http://www.artima.com/articles;p5
> > http://www.artima.com/articles
> >
> > And also:
> >
> > http://www.artima.com/articles;oa;tjava;p5;
> > http://www.artima.com/articles;p5;
> > http://www.artima.com/articles;
> >
> > Has anyone had any troubles in practice using URIs with params in
> > their segments?
>
> Not that I know of.
>
> > Are people moving towards this approach rather than query
> > parameters with their ?, &, and = chars?
>
> A few, but only when they are not using HTML forms to create the query.
> The vast majority just copy whatever they read in "CGI for Dummies".
> The only real difference is that some app frameworks will pre-parse
> the ?key=value args for you, so it is simpler to implement.
>
> It used to be that browsers and Squid would not cache any response
> containing a query segment, but that may have changed by now.
>
> ....Roy
>
>
>


-- 

Robert Sayre

"I would have written a shorter letter, but I did not have the time."

"Mike Schinkel" <mikeschinkel@...> writes:

> I made an assumption in my comments which you ferreted out; that yes I was
> talking about defaults where users of proxies and firewalls who barely have
> the skills (or the money) to get them up and running, let alone optimize
> them. With many organizations, even large one, use the same "Jell-O" model
> [1] for infrastructure configuration as some companies use for shipping
> software; when it stops quivering it's done!
>
> OTOH, Nic was speaking about the large organizations where one departments
> often didn't care about the concerns of others.

I think Elliotte is correct that we could fix the problem by getting
the proxy makers to change their proxies.

However, how long would it take to fix the problem. The big
organization that I was referring to had (amongst others) a Novell
Netware proxy server. It was at least 10 years old.

I recently made a trip to a medium sized company who were still using
Microsoft Proxy Server 1.0. I don't even want to think about how old
that is.


>
>> Indeed all you may need to do when a customer tells you your 
>> system seems broken is say, "Oh, you're using proxy X? That's 
>> broken and non-spec compliant. Use proxy Y instead and all 
>> will be fine."
>
> That's fine, assuming that information gets to the right person in the
> company (which is a huge assumption) and that the right person doesn't have
> other tasks they view as higher priority (which is another big
> assumption.)

I agree Mike. It's often really difficult to find out what is actually
causing the problem. Unless you have network access to the client site
in question it's almost impossible.

And Elliotte's assertion doesn't work at all if we're talking about a
web 2.0 business like digg or flikr. If those sites used PUT and it
failed for everyone nehind a crappy proxy just how many of those
failures would get reported to them?


> Unfortunately, only people who are drawn to the technology for personal
> interest see this as important enough to allow it to affect other factors.
> For another perspective on this, ask the WHATWG editor Ian Hickson if he
> thinks browser vendors will support standards that could potentially
> minimize their marketshare in any way.[2]  Almost no company will be willing
> to limit it's marketshare for a technical ideal. The way to achieve the
> technical ideal on as broad basis as possible is to make that support
> painless, not by ignoring market realities with the claim that "it is the
> right thing to do for the greater good." 

Spec compliance happens in the end. It just takes a long time.

Of course, it would help if broken and rubbish implementations didn't
get so widespread in the first place. But that's to do with the
ridiculous amounts of hype that drives our industry.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On 1/9/07, Mike Schinkel <mikeschinkel@...> wrote:
> However, the reason I was asking was because I was trying to gather evidence
> to present to Ian Hickson to support adding URI Template support to the
> action method of the form element in Web Forms 2.0.  I sent an email to
> uri@... to that effect[1], but got to response.

Though in theory that sounds like a great idea, it would break
existing clients which is a non-starter when defining HTML extensions.
 You'd need a new parameter to get around that problem.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Hi Nic,

On Jan 9, 2007, at 6:02 PM, Nic James Ferrier wrote:

> Bill Venners <bv-svp@...> writes:
>
>> I think segments are offset by slashes, so if you want /java to be
>> a ; param you'd probably need to encode it as in:
>>
>> http://www.artima.com/articles;p1=1;%2Fjava;p2=3
>>
>> Otherwise a relative link on that page of "fred.html" will attempt to
>> be grabbed from:
>>
>> http://www.artima.com/articles;p1=1;/fred.html
>
> You misunderstand my understanding of the spec   /8->
>
> I was trying to say that I think that each segment can have parameters
> associated with it, eg in the path:
>
>    /articles;p1=hello;p2=world/java;p3=nice;p5=day
>
> the segment "/articles" can have some parameters:
>
>   p1=hello
>   p2=world
>
> and the segment "/java" can have some parameters:
>
>   p4=nice
>   p5=day
>
>
> This certainly used to be the case. I'm not sure what the current
> situation is.
>
Ah, yes, that was my reading of the spec too. That's just not what I  
thought you meant. So you meant what you said, and said what you  
meant. Nevertheless, I am only considering putting semicolons at the  
end of the entire path.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Hi Robert,

On Jan 9, 2007, at 6:45 PM, Robert Sayre wrote:

> Caches ceased placing undue significance on the query string long ago.
> IIRC, that behavior became obsolete as PHP became more popular.
>
> Using query parameters in path segments is uninteresting. They make
> ugly object references, and most civilized web software translates
> human readable URLs to CGI environment variables using rewrite rules.
> See Rails,  Python Routes/WSGI, and good old mod_rewrite. In theory,
> structured path segments allow more versatile delegation of authority,
> but it doesn't seem economically compelling so far.
>
What do you mean by "in theory structured path segments allow more  
versatile delegation of authority?"

Also, I personally am not sure whether semicolon separated params  
would be prettier or uglier than traditional query params. The plus  
is with the semicolon approach our URIs could require one less char  
per query param (Since we're just using one char for the param name,  
we can drop the '='). The minus is that people are more used to  
seeing traditional query params and might find it harder to mentally  
extract the path part of our URIs if they are full of trailing  
semicolons, and I like to use the path part to help users figure out  
our information architecture. The other thing I'm considering is  
using an extra semicolon at the end to indicate a user is logged in,  
so I can make better use of caching. If params are already semicolon  
separated, tacking on an extra one at the end seems more natural.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

thanks for your help.

one final question, is it ok to model the API for 'status' as http://example.org/openQRM/service/abc123#status (thus stating more clearly it is a property of the service, and not a resource in itself)

thanks,
ittay

John D. Heintz wrote:
> 
> 
> Hello Ittay,
> 
> Here's how I would approach the problem by way of small example. I've 
> used "====..." just to help with the formatting.
> 
> The first thing I would do is break down the name/uri space like this:
> ============ ===
> GET http://example. org/openQRM/ service/abc123 
> <http://example.org/openQRM/service/abc123>
> ============ ===
> HTTP/1.1 200 OK
> 
> <?xml version="1.0" encoding="utf-8"?>
> ...
>     <service name="..." status="started" ...
> ============ ===
> 
> This indicates that we can get a representation of the service 
> identified by "abc123".
> 
> We could then PUT or POST a modifed representation with 
> status="stopped", but I'll take a different approach. Let's have the 
> represenation provide more information via the hypertext:
> 
> ============ ===
> GET http://example. org/openQRM/ service/abc123 
> <http://example.org/openQRM/service/abc123>
> ============ ===
> HTTP/1.1 200 OK
> 
> <?xml version="1.0" encoding="utf-8"?>
> ...
>     <service name="..." ...
>       <status current="started" href="abc123/status" ...
> ============ ==
> 
> Now we have marked a new URI that is specially designed for the status 
> of the "abc123" service.
> 
>  From that URI:
> ============ ===
> GET http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>
> ============ ===
> HTTP/1.1 200 OK
> 
> started
> ============ ===
> 
> Let's say that we want to support a simple PUT on this resource to 
> enable changing the state of a service:
> 
> ============ ===
> PUT http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>
> 
> stopped
> ============ ===
> HTTP/1.1 200 OK
> 
> stopped
> ============ ===
> 
> If ours was the only client controlling that service this would be 
> perfectly clear, but other clients (or the service itself) might have 
> already changed the status. Let's add some details that provide us with 
> information to do that.
> 
> ============ ===
> GET http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>
> ============ ===
> HTTP/1.1 200 OK
> Last-Modified: Tue, 09 Jan 2007 22:34:37 GMT
> ETag: "xyz-789"
> 
> started
> ============ ===
> 
> The Last-Modified should be clear, the ETag is a server-side hashed id 
> that can encode details like identity and version number. In our 
> subsequent PUT we can indicate to only do the work if the resource still 
> matches what we last saw (optimistic locking).
> 
> ============ ===
> PUT http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>
> If-Modified- Since: Tue, 09 Jan 2007 22:34:37 GMT
> 
> stopped
> ============ ===
> HTTP/1.1 200 OK
> 
> stopped
> ============ ===
> 
> Now it's safe for us to assume that "we" are the agent that did stop the 
> service. A failure response would have been returned if not.
> 
> Stuff that I've ignored so far:
> * content type: I'm just typing anything for example. Should always 
> prefer standard and interoperable content types.
> * content negotiation: browsers and B2B agents may not want the same 
> representation content types
> * Forms: How does this agent know it can PUT to that resource? What 
> values are allowed to be sent?
> * probably a bunch more, I hope others jump in to correct me ;)
> 
> Hope this helps provide a more clear example of the differences.
> 
> John
> 
> On 1/9/07, *Ittay Dror* < ittayd@qlusters. com 
> <mailto:ittayd@...>> wrote:
> 
>     what troubles me is that most examples i find to explain rest use
>     simple cases, where no logic is actually running, and so it is easy
>     to transfer services to properties (since the services do very little)
> 
>     so here is my real world use case: openQRM is a platform for
>     provisioning and managing services in a DC. a service is an entity
>     named VirtualEnvironment that encapsulates both a set of policies on
>     how to provision and manage the real service and a capture of the
>     real service's state (resources, utilization, error, etc.)
> 
>     we can do many actions on a service, but the primary ones are to
>     start and stop it. starting means resources are selected from a pool
>     and assigned to work for the service, the software is deployed on
>     them and the service is monitored. stopping is the reverse.
>     obviously openQRM does all this. the client just requests to 'start'
>     or 'stop'.
> 
>     now, it is hard for me to see 'start' and 'stop' as values of the
>     'currentactivity' property. if anything, it looks like a masquerade
>     of the RPC equivalent of posting to the VirtualEnvironment entity
>     with the pair 'action=start'.
> 
>     thank you for your help,
>     ittay
> 
>     wahbedahbe wrote:
>      >
>      >
>      > Hmmm. I'm a bit of a newbie too but let me take a stab at this as an
>      > exercise.
>      >
>      > Now let me first say that the way you posed the question is very
>      > "objecty" or "servicey" to begin with and makes it a bit hard to
>      > answer. You've basically said "I have a service with methods A,
>     B, and
>      > C; how do I make it resource based?" The problem is that REST has no
>      > concept of class-specific methods, so without knowing what A, B,
>     and C
>      > do, its hard to answer your question. In short, there is no straight
>      > forward transformation of an abstract service to abstract resources.
>      > (At least not that I know of...) They are two very different ways of
>      > modeling the interface. I can't transform one type of solution to
>      > another without understanding the problem.
>      >
>      > But I can infer a bit about the problem from the fact you are using
>      > the concept of a person and things a person can do (eat, sleep,
>     work).
>      > I'll assume here that sleep() and work() change the state of the
>      > person (to sleeping and working respectively) . Maybe there is a
>      > substate when working that says what work you are doing. Let's also
>      > assume that eat() adds some food items to a list of things eaten.
>      >
>      > So to work (on building a bike shed):
>      > PUT /person/ittay/ currentactivity
>      > Content-Type: application/ x-activity+ xml
>      >
>      > <activity>
>      > <type>work</ type>
>      > <sub-type>building a bike shed</sub-type>
>      > </activity>
>      >
>      > To sleep:
>      > PUT /person/ittay/ currentactivity
>      > Content-Type: application/ x-activity+ xml
>      >
>      > <activity>
>      > <type>sleep< /type>
>      > </activity>
>      >
>      > To eat an apple:
>      > POST /person/ittay/ stomach
>      > Content-type: application/ x-food+xml
>      >
>      > <food>apple< /food>
>      >
>      > Now these actions could also kick off related business processes. I
>      > think the only method that can't is GET. Note that you could use get
>      > to retrieve the current activity from /person/ittay/
>     currentactivity or
>      > the list of things eaten from /person/ittay/ stomach.
>      >
>      > --- In rest-discuss@ yahoogroups. com
>      > <mailto: rest-discuss% 40yahoogroups. com
>     <mailto:rest-discuss%40yahoogroups.com>>, Ittay Dror <ittayd@...> wrote:
>      >  >
>      >  > thanks for your example and site reference.
>      >  >
>      >  > i did know that i use only HTTP methods, what i lacked is how to
>      > model my business methods. i am a newbie at this (maybe i should have
>      > indicated that)
>      >  >
>      >  > may i impose with a followup?
>      >  >
>      >  > say i have a person entity in my application. this entity has
>      > several business methods (eat, sleep, work). how should i model a
>     rest
>      > api for these? create a PersonManager resource (which then will need
>      > to accept as argument what action to do), or create resources per
>      > action (/person/ittay/ eat maybe?).
>      >  >
>      >  > thanks,
>      >  > ittay
>      >  >
>      >  > Jan Algermissen wrote:
>      >  > > Hi Ittay,
>      >  > >
>      >  > > the kind of question you ask indicates that you have no yet
>      > understood a fundamental aspect of REST, namely that there is a
>      > uniform interface. You do not get any other methods as the
>     uniform set
>      > (the HTTP methods in the case of using HTTP as an architecture)
>      >  > >
>      >  > > Without any intention to be rude, I suggest you take a while to
>      > read through some of the REST material out on the Web (the REST wiki
>      > at http://rest <http://rest>. blueoxen. net <http://rest.
>     blueoxen. net <http://rest.blueoxen.net>> is a good
>      > starting point as is Paul's site
>      > at http://prescod. com/rest < http://prescod. com/rest
>     <http://prescod.com/rest>> ). This will help
>      > in future discussions.
>      >  > >
>      >  > >
>      >  > >> Should I use 'POST' with a 'method=build' parameter to the
>     'plan'
>      > URI?
>      >  > >
>      >  > > No, this is about the worst from a REST POV as it is hidden RPC.
>      >  > >
>      >  > > Think along these lines:
>      >  > >
>      >  > > Provide a means for clients to pick a resource that behaves the
>      > way they are interested in (some hypermedia the clients come accross
>      > could declare a resource as a BuildingManager) and then use POST to
>      > submit the building plan.
>      >  > >
>      >  > > POST /BuildingManager
>      >  > > Content-Type: application/ blueprint <-- this type is
>      > fictous; it would need to be standardized within the realm of
>     your system
>      >  > >
>      >  > > <blueprint>
>      >  > > <wall location=".. .."/>
>      >  > > </blueprint>
>      >  > >
>      >  > >
>      >  > > IOW, in a RESTful system clients late-bind to resources based on
>      > runtime-declared abstract bahavior of those resources and they
>      > communicate via a fixed set of methods.
>      >  > >
>      >  > > HTH,
>      >  > >
>      >  > > Jan
>      >  > >
>      >  > >
>      >  > >
>      >  > >
>      >  > >
>      >  > >> Thanks,
>      >  > >> Ittay
>      >  > >>
>      >  > >>
>      >  > >>
>      >  > >>
>      >  > >> Yahoo! Groups Links
>      >  > >>
>      >  > >>
>      >  > >>
>      >  > >>
>      >  > >>
>      >  > >
>      >  >
>      >  >
>      >  > --
>      >  > ============ ========= ========= =====
>      >  > Ittay Dror,
>      >  > Chief architect,
>      >  > R&D, Qlusters Inc.
>      >  > ittayd@...
>      >  > +972-3-6081994 Fax: +972-3-6081841
>      >  >
>      >  > www.openqrm. org - Data Center Provisioning
>      >  >
>      >
>      >
> 
> 
>     --
>     ============ ========= ========= =====
>     Ittay Dror,
>     Chief architect,
>     R&D, Qlusters Inc.
>     ittayd@qlusters. com <mailto:ittayd@...>
>     +972-3-6081994 Fax: +972-3-6081841
> 
>     www.openqrm. org <http://www.openqrm.org> - Data Center Provisioning
> 
> 
> 
>     Yahoo! Groups Links
> 
> 
>         (Yahoo! ID required)
> 
>         mailto:rest-discuss- fullfeatured@ yahoogroups. com
>     <mailto:rest-discuss-fullfeatured@yahoogroups.com>
> 
> 
> 
> 
> 
> 
> -- 
> John D. Heintz
> Principal Consultant
> New Aspects of Software
> Austin, TX
> (512) 633-1198
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

bad choice of characters. '#' is for fragment identifiers. maybe
something like:
http://example.org/openQRM/service/abc123:status

and another question, is it ok to model the 'start' and 'stop' actions
as 'action' resources?

so, POST to http://example.org/openQRM/actions/start with data
http://example.org/openQRM/service/abc123

thanks,
ittay

Ittay Dror wrote:
> 
> 
> thanks for your help.
> 
> one final question, is it ok to model the API for 'status' as 
> http://example. org/openQRM/ service/abc123# status 
> <http://example.org/openQRM/service/abc123#status> (thus stating more 
> clearly it is a property of the service, and not a resource in itself)
> 
> thanks,
> ittay
> 
> John D. Heintz wrote:
>  >
>  >
>  > Hello Ittay,
>  >
>  > Here's how I would approach the problem by way of small example. I've
>  > used "====..." just to help with the formatting.
>  >
>  > The first thing I would do is break down the name/uri space like this:
>  > ============ ===
>  > GET http://example. org/openQRM/ service/abc123
>  > <http://example. org/openQRM/ service/abc123 
> <http://example.org/openQRM/service/abc123>>
>  > ============ ===
>  > HTTP/1.1 200 OK
>  >
>  > <?xml version="1.0" encoding="utf- 8"?>
>  > ...
>  > <service name="..." status="started" ...
>  > ============ ===
>  >
>  > This indicates that we can get a representation of the service
>  > identified by "abc123".
>  >
>  > We could then PUT or POST a modifed representation with
>  > status="stopped" , but I'll take a different approach. Let's have the
>  > represenation provide more information via the hypertext:
>  >
>  > ============ ===
>  > GET http://example. org/openQRM/ service/abc123
>  > <http://example. org/openQRM/ service/abc123 
> <http://example.org/openQRM/service/abc123>>
>  > ============ ===
>  > HTTP/1.1 200 OK
>  >
>  > <?xml version="1.0" encoding="utf- 8"?>
>  > ...
>  > <service name="..." ...
>  > <status current="started" href="abc123/ status" ...
>  > ============ ==
>  >
>  > Now we have marked a new URI that is specially designed for the status
>  > of the "abc123" service.
>  >
>  > From that URI:
>  > ============ ===
>  > GET http://example. org/openQRM/ service/abc123/ status
>  > <http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>>
>  > ============ ===
>  > HTTP/1.1 200 OK
>  >
>  > started
>  > ============ ===
>  >
>  > Let's say that we want to support a simple PUT on this resource to
>  > enable changing the state of a service:
>  >
>  > ============ ===
>  > PUT http://example. org/openQRM/ service/abc123/ status
>  > <http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>>
>  >
>  > stopped
>  > ============ ===
>  > HTTP/1.1 200 OK
>  >
>  > stopped
>  > ============ ===
>  >
>  > If ours was the only client controlling that service this would be
>  > perfectly clear, but other clients (or the service itself) might have
>  > already changed the status. Let's add some details that provide us with
>  > information to do that.
>  >
>  > ============ ===
>  > GET http://example. org/openQRM/ service/abc123/ status
>  > <http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>>
>  > ============ ===
>  > HTTP/1.1 200 OK
>  > Last-Modified: Tue, 09 Jan 2007 22:34:37 GMT
>  > ETag: "xyz-789"
>  >
>  > started
>  > ============ ===
>  >
>  > The Last-Modified should be clear, the ETag is a server-side hashed id
>  > that can encode details like identity and version number. In our
>  > subsequent PUT we can indicate to only do the work if the resource still
>  > matches what we last saw (optimistic locking).
>  >
>  > ============ ===
>  > PUT http://example. org/openQRM/ service/abc123/ status
>  > <http://example. org/openQRM/ service/abc123/ status 
> <http://example.org/openQRM/service/abc123/status>>
>  > If-Modified- Since: Tue, 09 Jan 2007 22:34:37 GMT
>  >
>  > stopped
>  > ============ ===
>  > HTTP/1.1 200 OK
>  >
>  > stopped
>  > ============ ===
>  >
>  > Now it's safe for us to assume that "we" are the agent that did stop the
>  > service. A failure response would have been returned if not.
>  >
>  > Stuff that I've ignored so far:
>  > * content type: I'm just typing anything for example. Should always
>  > prefer standard and interoperable content types.
>  > * content negotiation: browsers and B2B agents may not want the same
>  > representation content types
>  > * Forms: How does this agent know it can PUT to that resource? What
>  > values are allowed to be sent?
>  > * probably a bunch more, I hope others jump in to correct me ;)
>  >
>  > Hope this helps provide a more clear example of the differences.
>  >
>  > John
>  >
>  > On 1/9/07, *Ittay Dror* < ittayd@qlusters. com
>  > <mailto:ittayd@qlusters. com <mailto:ittayd%40qlusters.com>>> wrote:
>  >
>  > what troubles me is that most examples i find to explain rest use
>  > simple cases, where no logic is actually running, and so it is easy
>  > to transfer services to properties (since the services do very little)
>  >
>  > so here is my real world use case: openQRM is a platform for
>  > provisioning and managing services in a DC. a service is an entity
>  > named VirtualEnvironment that encapsulates both a set of policies on
>  > how to provision and manage the real service and a capture of the
>  > real service's state (resources, utilization, error, etc.)
>  >
>  > we can do many actions on a service, but the primary ones are to
>  > start and stop it. starting means resources are selected from a pool
>  > and assigned to work for the service, the software is deployed on
>  > them and the service is monitored. stopping is the reverse.
>  > obviously openQRM does all this. the client just requests to 'start'
>  > or 'stop'.
>  >
>  > now, it is hard for me to see 'start' and 'stop' as values of the
>  > 'currentactivity' property. if anything, it looks like a masquerade
>  > of the RPC equivalent of posting to the VirtualEnvironment entity
>  > with the pair 'action=start' .
>  >
>  > thank you for your help,
>  > ittay
>  >
>  > wahbedahbe wrote:
>  > >
>  > >
>  > > Hmmm. I'm a bit of a newbie too but let me take a stab at this as an
>  > > exercise.
>  > >
>  > > Now let me first say that the way you posed the question is very
>  > > "objecty" or "servicey" to begin with and makes it a bit hard to
>  > > answer. You've basically said "I have a service with methods A,
>  > B, and
>  > > C; how do I make it resource based?" The problem is that REST has no
>  > > concept of class-specific methods, so without knowing what A, B,
>  > and C
>  > > do, its hard to answer your question. In short, there is no straight
>  > > forward transformation of an abstract service to abstract resources.
>  > > (At least not that I know of...) They are two very different ways of
>  > > modeling the interface. I can't transform one type of solution to
>  > > another without understanding the problem.
>  > >
>  > > But I can infer a bit about the problem from the fact you are using
>  > > the concept of a person and things a person can do (eat, sleep,
>  > work).
>  > > I'll assume here that sleep() and work() change the state of the
>  > > person (to sleeping and working respectively) . Maybe there is a
>  > > substate when working that says what work you are doing. Let's also
>  > > assume that eat() adds some food items to a list of things eaten.
>  > >
>  > > So to work (on building a bike shed):
>  > > PUT /person/ittay/ currentactivity
>  > > Content-Type: application/ x-activity+ xml
>  > >
>  > > <activity>
>  > > <type>work</ type>
>  > > <sub-type>building a bike shed</sub-type>
>  > > </activity>
>  > >
>  > > To sleep:
>  > > PUT /person/ittay/ currentactivity
>  > > Content-Type: application/ x-activity+ xml
>  > >
>  > > <activity>
>  > > <type>sleep< /type>
>  > > </activity>
>  > >
>  > > To eat an apple:
>  > > POST /person/ittay/ stomach
>  > > Content-type: application/ x-food+xml
>  > >
>  > > <food>apple< /food>
>  > >
>  > > Now these actions could also kick off related business processes. I
>  > > think the only method that can't is GET. Note that you could use get
>  > > to retrieve the current activity from /person/ittay/
>  > currentactivity or
>  > > the list of things eaten from /person/ittay/ stomach.
>  > >
>  > > --- In rest-discuss@ yahoogroups. com
>  > > <mailto: rest-discuss% 40yahoogroups. com
>  > <mailto:rest- discuss%40yahoog roups.com> >, Ittay Dror <ittayd@...> 
> wrote:
>  > > >
>  > > > thanks for your example and site reference.
>  > > >
>  > > > i did know that i use only HTTP methods, what i lacked is how to
>  > > model my business methods. i am a newbie at this (maybe i should have
>  > > indicated that)
>  > > >
>  > > > may i impose with a followup?
>  > > >
>  > > > say i have a person entity in my application. this entity has
>  > > several business methods (eat, sleep, work). how should i model a
>  > rest
>  > > api for these? create a PersonManager resource (which then will need
>  > > to accept as argument what action to do), or create resources per
>  > > action (/person/ittay/ eat maybe?).
>  > > >
>  > > > thanks,
>  > > > ittay
>  > > >
>  > > > Jan Algermissen wrote:
>  > > > > Hi Ittay,
>  > > > >
>  > > > > the kind of question you ask indicates that you have no yet
>  > > understood a fundamental aspect of REST, namely that there is a
>  > > uniform interface. You do not get any other methods as the
>  > uniform set
>  > > (the HTTP methods in the case of using HTTP as an architecture)
>  > > > >
>  > > > > Without any intention to be rude, I suggest you take a while to
>  > > read through some of the REST material out on the Web (the REST wiki
>  > > at http://rest <http://rest>. blueoxen. net <http://rest.
>  > blueoxen. net <http://rest. blueoxen. net 
> <http://rest.blueoxen.net>>> is a good
>  > > starting point as is Paul's site
>  > > at http://prescod. com/rest < http://prescod. com/rest
>  > <http://prescod. com/rest <http://prescod.com/rest>>> ). This will help
>  > > in future discussions.
>  > > > >
>  > > > >
>  > > > >> Should I use 'POST' with a 'method=build' parameter to the
>  > 'plan'
>  > > URI?
>  > > > >
>  > > > > No, this is about the worst from a REST POV as it is hidden RPC.
>  > > > >
>  > > > > Think along these lines:
>  > > > >
>  > > > > Provide a means for clients to pick a resource that behaves the
>  > > way they are interested in (some hypermedia the clients come accross
>  > > could declare a resource as a BuildingManager) and then use POST to
>  > > submit the building plan.
>  > > > >
>  > > > > POST /BuildingManager
>  > > > > Content-Type: application/ blueprint <-- this type is
>  > > fictous; it would need to be standardized within the realm of
>  > your system
>  > > > >
>  > > > > <blueprint>
>  > > > > <wall location=".. .."/>
>  > > > > </blueprint>
>  > > > >
>  > > > >
>  > > > > IOW, in a RESTful system clients late-bind to resources based on
>  > > runtime-declared abstract bahavior of those resources and they
>  > > communicate via a fixed set of methods.
>  > > > >
>  > > > > HTH,
>  > > > >
>  > > > > Jan
>  > > > >
>  > > > >
>  > > > >
>  > > > >
>  > > > >
>  > > > >> Thanks,
>  > > > >> Ittay
>  > > > >>
>  > > > >>
>  > > > >>
>  > > > >>
>  > > > >> Yahoo! Groups Links
>  > > > >>
>  > > > >>
>  > > > >>
>  > > > >>
>  > > > >>
>  > > > >
>  > > >
>  > > >
>  > > > --
>  > > > ============ ========= ========= =====
>  > > > Ittay Dror,
>  > > > Chief architect,
>  > > > R&D, Qlusters Inc.
>  > > > ittayd@...
>  > > > +972-3-6081994 Fax: +972-3-6081841
>  > > >
>  > > > www.openqrm. org - Data Center Provisioning
>  > > >
>  > >
>  > >
>  >
>  >
>  > --
>  > ============ ========= ========= =====
>  > Ittay Dror,
>  > Chief architect,
>  > R&D, Qlusters Inc.
>  > ittayd@qlusters. com <mailto:ittayd@qlusters. com 
> <mailto:ittayd%40qlusters.com>>
>  > +972-3-6081994 Fax: +972-3-6081841
>  >
>  > www.openqrm. org <http://www.openqrm. org <http://www.openqrm.org>> - 
> Data Center Provisioning
>  >
>  >
>  >
>  > Yahoo! Groups Links
>  >
>  >
>  > (Yahoo! ID required)
>  >
>  > mailto:rest- discuss- fullfeatured@ yahoogroups. com
>  > <mailto:rest-discuss- fullfeatured@ yahoogroups. com 
> <mailto:rest-discuss-fullfeatured%40yahoogroups.com>>
>  >
>  >
>  >
>  >
>  >
>  >
>  > --
>  > John D. Heintz
>  > Principal Consultant
>  > New Aspects of Software
>  > Austin, TX
>  > (512) 633-1198
>  >
> 
> -- 
> ============ ========= ========= =====
> Ittay Dror,
> Chief architect,
> R&D, Qlusters Inc.
> ittayd@qlusters. com <mailto:ittayd%40qlusters.com>
> +972-3-6081994 Fax: +972-3-6081841
> 
> www.openqrm. org - Data Center Provisioning
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

> 
> say i have a person entity in my application. this entity has 
> several business methods (eat, sleep, work). how should i 
> model a rest api for these? create a PersonManager resource 
> (which then will need to accept as argument what action to 
> do), or create resources per action (/person/ittay/eat maybe?). 
Rather than modeling an API as having many methods, model the application as
kinds of resources and their states. 
A resource has an identifier and a representation (it could have several
representations, but we should keep the example simple for now). A client
sets or gets the state of a resource, then takes action based on the
responses to setting or getting the data.

Perhaps rather than invoking a "person[27].eat()" method, you could add to
the "person[27].goals" a value of "eat".

POST /people/ittay/goals HTTP/1.1
Host: www.dror.com
Content-Type: application/xml

<goals>
 <goal priority="high">eat</goal>
</goals>

The server may decide that the request to eat is inappropriate, or the
server may schedule the activity for later, or it may immediately take
action - these could be indicated in a response that points to the current
activities:

201 Created
Location: /people/ittay/activities

<activities>
 <activity>watch television</activity>
 <activity>eat</activity>
</activities>

> 
> now, it is hard for me to see 'start' and 'stop' as values of 
> the 'currentactivity' property. if anything, it looks like a 
> masquerade of the RPC equivalent of posting to the 
> VirtualEnvironment entity with the pair 'action=start'. 
What happens if a client sends 'start' twice? In a state transition diagram,
that would be fairly easy to describe the desired behavior. In an 'action
oriented' approach, you'd have to special case that to prevent multiple
initializations/etc. 

Hey all:

Someone sent me a link to Conduit's website [1] related to a project I'm
working on.  After looking at their website I learned they allow you to
configure a company or community specific toolbar at their website that will
install into IE or Firefox, and then distribute to customers/community
members.  They get their revenue by serving Google searches from their
toolbar where they get a cut of the ad revenue, but it's almost completely
seemless to the user.

To test it I used one of their default templates for a Yahoo Group and then
customized it a bit. I chose to create one for REST-discuss, and though I'm
not normally a toolbar fan, after I was finished I was pleasently surprised
at its usability! It allows you to:

-- Search REST Discuss using Google (I could configure to also search other
engines if anyone cares)
-- Reference an RSS Feed of recent REST-discuss messages from the toolbar
-- Have a chat among any REST-discuss toolbar users (currently there are
none, but if a lot of people used it...)
-- Allow us to send messages to REST-discuss toolbar users
-- There's a drop down menu with links to all major sections on the
REST-Discuss page
-- I added a drop down menu of links to the best articles and most important
RFCs and W3C specs (although I might have missed some.)
-- And a ticker I think you'll find amusing. :)  (You can turn it off if you
don't like it.)

Again, this thing is suprisingly devoid of anything that would smack of in
your face advertising. I think they've got the web 2.0 ethos down. 

Try it out [2], and let me know what you think. I'm definitely going to keep
it installed on my browsers.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
P.S. For the cynics in the audience, I don't benefit from people using this
in any way. I didn't include any links to any of my sites and I won't get
any affliate revenue if you use this. I just thought it was cool and useful
for REST-discuss community. And the company offering this, Conduit, appears
to be legit with a lot of traffic on their forum where a lot of people
seeming to be positive about them and their answers about their revenue
model seem to jive with reality. 

[1] http://www.conduit.com/
[2] http://restdiscuss.communitytoolbars.com/

S. Mike Dierken wrote:
>> now, it is hard for me to see 'start' and 'stop' as values of 
>> the 'currentactivity' property. if anything, it looks like a 
>> masquerade of the RPC equivalent of posting to the 
>> VirtualEnvironment entity with the pair 'action=start'. 
> What happens if a client sends 'start' twice? In a state transition diagram,
> that would be fairly easy to describe the desired behavior. In an 'action

can you please elaborate? 

> oriented' approach, you'd have to special case that to prevent multiple
> initializations/etc. 
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

S. Mike Dierken wrote:
> How about a '/' character?
>  GET http://example.org/openQRM/service/abc123/status 
> You could even use query terms
>  GET http://example.org/openQRM/service/abc123?property=status 
> 
>> and another question, is it ok to model the 'start' and 'stop' actions as
> 'action' resources?
> Sure - if you want to dynamically define and re-define the implementation of
> the 'start' action, like upload some script. (I built a system like that
> once, it was very cool.)
> But I think this model is headed towards a queue, where you add work
> (pointers to entities) to be done.

yes. naturally, i would do it by sending a '<start>http://example.org/openQRM/service/abc123</start>'  data to the http://example.org/openQRM/actions resource (a queue of actions), or http://example.org/openQRM/service/abc123/actions. but this then seems very RPC


> 
> 
> 
>> -----Original Message-----
>> From: rest-discuss@yahoogroups.com 
>> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Ittay Dror
>> Sent: Tuesday, January 09, 2007 10:26 PM
>> To: rest-discuss@yahoogroups.com
>> Subject: Re: [rest-discuss] Re: how to model actions
>>
>> bad choice of characters. '#' is for fragment identifiers. 
>> maybe something like:
>> http://example.org/openQRM/service/abc123:status
>>
>> and another question, is it ok to model the 'start' and 
>> 'stop' actions as 'action' resources?
>>
>> so, POST to http://example.org/openQRM/actions/start with data
>> http://example.org/openQRM/service/abc123
>>
>> thanks,
>> ittay
>>
>> Ittay Dror wrote:
>>>
>>> thanks for your help.
>>>
>>> one final question, is it ok to model the API for 'status' as 
>>> http://example. org/openQRM/ service/abc123# status 
>>> <http://example.org/openQRM/service/abc123#status> (thus 
>> stating more 
>>> clearly it is a property of the service, and not a resource 
>> in itself)
>>> thanks,
>>> ittay
>>>
>>> John D. Heintz wrote:
>>>  >
>>>  >
>>>  > Hello Ittay,
>>>  >
>>>  > Here's how I would approach the problem by way of small example. 
>>> I've  > used "====..." just to help with the formatting.
>>>  >
>>>  > The first thing I would do is break down the name/uri 
>> space like this:
>>>  > ============ ===
>>>  > GET http://example. org/openQRM/ service/abc123  > 
>> <http://example. 
>>> org/openQRM/ service/abc123 
>>> <http://example.org/openQRM/service/abc123>>
>>>  > ============ ===
>>>  > HTTP/1.1 200 OK
>>>  >
>>>  > <?xml version="1.0" encoding="utf- 8"?>  > ...
>>>  > <service name="..." status="started" ...
>>>  > ============ ===
>>>  >
>>>  > This indicates that we can get a representation of the 
>> service  > 
>>> identified by "abc123".
>>>  >
>>>  > We could then PUT or POST a modifed representation with  > 
>>> status="stopped" , but I'll take a different approach. 
>> Let's have the  
>>>> represenation provide more information via the hypertext:
>>>  >
>>>  > ============ ===
>>>  > GET http://example. org/openQRM/ service/abc123  > 
>> <http://example. 
>>> org/openQRM/ service/abc123 
>>> <http://example.org/openQRM/service/abc123>>
>>>  > ============ ===
>>>  > HTTP/1.1 200 OK
>>>  >
>>>  > <?xml version="1.0" encoding="utf- 8"?>  > ...
>>>  > <service name="..." ...
>>>  > <status current="started" href="abc123/ status" ...
>>>  > ============ ==
>>>  >
>>>  > Now we have marked a new URI that is specially designed for the 
>>> status  > of the "abc123" service.
>>>  >
>>>  > From that URI:
>>>  > ============ ===
>>>  > GET http://example. org/openQRM/ service/abc123/ status  > 
>>> <http://example. org/openQRM/ service/abc123/ status 
>>> <http://example.org/openQRM/service/abc123/status>>
>>>  > ============ ===
>>>  > HTTP/1.1 200 OK
>>>  >
>>>  > started
>>>  > ============ ===
>>>  >
>>>  > Let's say that we want to support a simple PUT on this 
>> resource to  
>>>> enable changing the state of a service:
>>>  >
>>>  > ============ ===
>>>  > PUT http://example. org/openQRM/ service/abc123/ status  > 
>>> <http://example. org/openQRM/ service/abc123/ status 
>>> <http://example.org/openQRM/service/abc123/status>>
>>>  >
>>>  > stopped
>>>  > ============ ===
>>>  > HTTP/1.1 200 OK
>>>  >
>>>  > stopped
>>>  > ============ ===
>>>  >
>>>  > If ours was the only client controlling that service 
>> this would be  
>>>> perfectly clear, but other clients (or the service itself) might 
>>> have  > already changed the status. Let's add some details that 
>>> provide us with  > information to do that.
>>>  >
>>>  > ============ ===
>>>  > GET http://example. org/openQRM/ service/abc123/ status  > 
>>> <http://example. org/openQRM/ service/abc123/ status 
>>> <http://example.org/openQRM/service/abc123/status>>
>>>  > ============ ===
>>>  > HTTP/1.1 200 OK
>>>  > Last-Modified: Tue, 09 Jan 2007 22:34:37 GMT  > ETag: "xyz-789"
>>>  >
>>>  > started
>>>  > ============ ===
>>>  >
>>>  > The Last-Modified should be clear, the ETag is a 
>> server-side hashed 
>>> id  > that can encode details like identity and version 
>> number. In our  
>>>> subsequent PUT we can indicate to only do the work if the 
>> resource 
>>> still  > matches what we last saw (optimistic locking).
>>>  >
>>>  > ============ ===
>>>  > PUT http://example. org/openQRM/ service/abc123/ status  > 
>>> <http://example. org/openQRM/ service/abc123/ status 
>>> <http://example.org/openQRM/service/abc123/status>>
>>>  > If-Modified- Since: Tue, 09 Jan 2007 22:34:37 GMT  >  > 
>> stopped  > 
>>> ============ ===  > HTTP/1.1 200 OK  >  > stopped  > 
>> ============ ===  
>>>>  > Now it's safe for us to assume that "we" are the agent 
>> that did 
>>> stop the  > service. A failure response would have been returned if 
>>> not.
>>>  >
>>>  > Stuff that I've ignored so far:
>>>  > * content type: I'm just typing anything for example. 
>> Should always  
>>>> prefer standard and interoperable content types.
>>>  > * content negotiation: browsers and B2B agents may not want the 
>>> same  > representation content types  > * Forms: How does 
>> this agent 
>>> know it can PUT to that resource? What  > values are allowed to be 
>>> sent?
>>>  > * probably a bunch more, I hope others jump in to 
>> correct me ;)  >  
>>>> Hope this helps provide a more clear example of the differences.
>>>  >
>>>  > John
>>>  >
>>>  > On 1/9/07, *Ittay Dror* < ittayd@qlusters. com  > 
>>> <mailto:ittayd@qlusters. com <mailto:ittayd%40qlusters.com>>> wrote:
>>>  >
>>>  > what troubles me is that most examples i find to explain 
>> rest use  
>>>> simple cases, where no logic is actually running, and so 
>> it is easy  
>>>> to transfer services to properties (since the services do very 
>>> little)  >  > so here is my real world use case: openQRM is 
>> a platform 
>>> for  > provisioning and managing services in a DC. a service is an 
>>> entity  > named VirtualEnvironment that encapsulates both a set of 
>>> policies on  > how to provision and manage the real service and a 
>>> capture of the  > real service's state (resources, 
>> utilization, error, 
>>> etc.)  >  > we can do many actions on a service, but the 
>> primary ones 
>>> are to  > start and stop it. starting means resources are selected 
>>> from a pool  > and assigned to work for the service, the 
>> software is 
>>> deployed on  > them and the service is monitored. stopping is the 
>>> reverse.
>>>  > obviously openQRM does all this. the client just 
>> requests to 'start'
>>>  > or 'stop'.
>>>  >
>>>  > now, it is hard for me to see 'start' and 'stop' as 
>> values of the  
>>>> 'currentactivity' property. if anything, it looks like a 
>> masquerade  
>>>> of the RPC equivalent of posting to the 
>> VirtualEnvironment entity  > 
>>> with the pair 'action=start' .
>>>  >
>>>  > thank you for your help,
>>>  > ittay
>>>  >
>>>  > wahbedahbe wrote:
>>>  > >
>>>  > >
>>>  > > Hmmm. I'm a bit of a newbie too but let me take a stab 
>> at this as 
>>> an  > > exercise.
>>>  > >
>>>  > > Now let me first say that the way you posed the 
>> question is very  
>>>>> "objecty" or "servicey" to begin with and makes it a 
>> bit hard to  
>>>>> answer. You've basically said "I have a service with 
>> methods A,  > 
>>> B, and  > > C; how do I make it resource based?" The 
>> problem is that 
>>> REST has no  > > concept of class-specific methods, so 
>> without knowing 
>>> what A, B,  > and C  > > do, its hard to answer your question. In 
>>> short, there is no straight  > > forward transformation of 
>> an abstract 
>>> service to abstract resources.
>>>  > > (At least not that I know of...) They are two very 
>> different ways 
>>> of  > > modeling the interface. I can't transform one type 
>> of solution 
>>> to  > > another without understanding the problem.
>>>  > >
>>>  > > But I can infer a bit about the problem from the fact you are 
>>> using  > > the concept of a person and things a person can do (eat, 
>>> sleep,  > work).
>>>  > > I'll assume here that sleep() and work() change the 
>> state of the  
>>>>> person (to sleeping and working respectively) . Maybe 
>> there is a  
>>>>> substate when working that says what work you are doing. Let's 
>>> also  > > assume that eat() adds some food items to a list 
>> of things eaten.
>>>  > >
>>>  > > So to work (on building a bike shed):
>>>  > > PUT /person/ittay/ currentactivity  > > Content-Type: 
>>> application/ x-activity+ xml  > >  > > <activity>  > > <type>work</ 
>>> type>  > > <sub-type>building a bike shed</sub-type>  > > 
>> </activity>  
>>>>>  > > To sleep:
>>>  > > PUT /person/ittay/ currentactivity  > > Content-Type: 
>>> application/ x-activity+ xml  > >  > > <activity>  > > <type>sleep< 
>>> /type>  > > </activity>  > >  > > To eat an apple:
>>>  > > POST /person/ittay/ stomach
>>>  > > Content-type: application/ x-food+xml  > >  > > <food>apple< 
>>> /food>  > >  > > Now these actions could also kick off related 
>>> business processes. I  > > think the only method that can't is GET. 
>>> Note that you could use get  > > to retrieve the current 
>> activity from 
>>> /person/ittay/  > currentactivity or  > > the list of things eaten 
>>> from /person/ittay/ stomach.
>>>  > >
>>>  > > --- In rest-discuss@ yahoogroups. com  > > <mailto: 
>> rest-discuss% 
>>> 40yahoogroups. com  > <mailto:rest- discuss%40yahoog roups.com> >, 
>>> Ittay Dror <ittayd@...>
>>> wrote:
>>>  > > >
>>>  > > > thanks for your example and site reference.
>>>  > > >
>>>  > > > i did know that i use only HTTP methods, what i 
>> lacked is how 
>>> to  > > model my business methods. i am a newbie at this (maybe i 
>>> should have  > > indicated that)  > > >  > > > may i impose with a 
>>> followup?
>>>  > > >
>>>  > > > say i have a person entity in my application. this 
>> entity has  
>>>>> several business methods (eat, sleep, work). how should 
>> i model a  
>>>> rest  > > api for these? create a PersonManager resource 
>> (which then 
>>> will need  > > to accept as argument what action to do), or create 
>>> resources per  > > action (/person/ittay/ eat maybe?).
>>>  > > >
>>>  > > > thanks,
>>>  > > > ittay
>>>  > > >
>>>  > > > Jan Algermissen wrote:
>>>  > > > > Hi Ittay,
>>>  > > > >
>>>  > > > > the kind of question you ask indicates that you 
>> have no yet  
>>>>> understood a fundamental aspect of REST, namely that 
>> there is a  > 
>>>> uniform interface. You do not get any other methods as the  > 
>>> uniform set  > > (the HTTP methods in the case of using HTTP as an 
>>> architecture)  > > > >  > > > > Without any intention to be rude, I 
>>> suggest you take a while to  > > read through some of the REST 
>>> material out on the Web (the REST wiki  > > at http://rest 
>>> <http://rest>. blueoxen. net <http://rest.
>>>  > blueoxen. net <http://rest. blueoxen. net 
>>> <http://rest.blueoxen.net>>> is a good  > > starting point as is 
>>> Paul's site  > > at http://prescod. com/rest < http://prescod. 
>>> com/rest  > <http://prescod. com/rest 
>> <http://prescod.com/rest>>> ). 
>>> This will help  > > in future discussions.
>>>  > > > >
>>>  > > > >
>>>  > > > >> Should I use 'POST' with a 'method=build' 
>> parameter to the  
>>>> 'plan'
>>>  > > URI?
>>>  > > > >
>>>  > > > > No, this is about the worst from a REST POV as it 
>> is hidden RPC.
>>>  > > > >
>>>  > > > > Think along these lines:
>>>  > > > >
>>>  > > > > Provide a means for clients to pick a resource 
>> that behaves 
>>> the  > > way they are interested in (some hypermedia the 
>> clients come 
>>> accross  > > could declare a resource as a BuildingManager) 
>> and then 
>>> use POST to  > > submit the building plan.
>>>  > > > >
>>>  > > > > POST /BuildingManager
>>>  > > > > Content-Type: application/ blueprint <-- this type is  > > 
>>> fictous; it would need to be standardized within the realm 
>> of  > your 
>>> system  > > > >  > > > > <blueprint>  > > > > <wall 
>> location=".. .."/>  
>>>>>>> </blueprint>  > > > >  > > > >  > > > > IOW, in a RESTful 
>>> system clients late-bind to resources based on  > > 
>> runtime-declared 
>>> abstract bahavior of those resources and they  > > 
>> communicate via a 
>>> fixed set of methods.
>>>  > > > >
>>>  > > > > HTH,
>>>  > > > >
>>>  > > > > Jan
>>>  > > > >
>>>  > > > >
>>>  > > > >
>>>  > > > >
>>>  > > > >
>>>  > > > >> Thanks,
>>>  > > > >> Ittay
>>>  > > > >>
>>>  > > > >>
>>>  > > > >>
>>>  > > > >>
>>>  > > > >> Yahoo! Groups Links
>>>  > > > >>
>>>  > > > >>
>>>  > > > >>
>>>  > > > >>
>>>  > > > >>
>>>  > > > >
>>>  > > >
>>>  > > >
>>>  > > > --
>>>  > > > ============ ========= ========= =====  > > > Ittay 
>> Dror,  > > 
>>>> Chief architect,  > > > R&D, Qlusters Inc.
>>>  > > > ittayd@...
>>>  > > > +972-3-6081994 Fax: +972-3-6081841  > > >  > > > 
>> www.openqrm. 
>>> org - Data Center Provisioning  > > >  > >  > >  >  >  > --  > 
>>> ============ ========= ========= =====  > Ittay Dror,  > Chief 
>>> architect,  > R&D, Qlusters Inc.
>>>  > ittayd@qlusters. com <mailto:ittayd@qlusters. com 
>>> <mailto:ittayd%40qlusters.com>>  > +972-3-6081994 Fax: 
>> +972-3-6081841  
>>>>  > www.openqrm. org <http://www.openqrm. org 
>>> <http://www.openqrm.org>> - Data Center Provisioning  >  >  >  > 
>>> Yahoo! Groups Links  >  >  > (Yahoo! ID required)  >  > 
>> mailto:rest- 
>>> discuss- fullfeatured@ yahoogroups. com  > <mailto:rest-discuss- 
>>> fullfeatured@ yahoogroups. com 
>>> <mailto:rest-discuss-fullfeatured%40yahoogroups.com>>
>>>  >
>>>  >
>>>  >
>>>  >
>>>  >
>>>  >
>>>  > --
>>>  > John D. Heintz
>>>  > Principal Consultant
>>>  > New Aspects of Software
>>>  > Austin, TX
>>>  > (512) 633-1198
>>>  >
>>>
>>> --
>>> ============ ========= ========= ===== Ittay Dror, Chief architect, 
>>> R&D, Qlusters Inc.
>>> ittayd@qlusters. com <mailto:ittayd%40qlusters.com>
>>> +972-3-6081994 Fax: +972-3-6081841
>>>
>>> www.openqrm. org - Data Center Provisioning
>>>
>>>
>>
>> --
>> ===================================
>> Ittay Dror,
>> Chief architect,
>> R&D, Qlusters Inc.
>> ittayd@...
>> +972-3-6081994 Fax: +972-3-6081841
>>
>> www.openqrm.org - Data Center Provisioning
>>
>>
>>  
>> Yahoo! Groups Links
>>
>>
>>
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

How about a '/' character?
 GET http://example.org/openQRM/service/abc123/status 
You could even use query terms
 GET http://example.org/openQRM/service/abc123?property=status 

> and another question, is it ok to model the 'start' and 'stop' actions as
'action' resources?
Sure - if you want to dynamically define and re-define the implementation of
the 'start' action, like upload some script. (I built a system like that
once, it was very cool.)
But I think this model is headed towards a queue, where you add work
(pointers to entities) to be done.



> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Ittay Dror
> Sent: Tuesday, January 09, 2007 10:26 PM
> To: rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] Re: how to model actions
> 
> bad choice of characters. '#' is for fragment identifiers. 
> maybe something like:
> http://example.org/openQRM/service/abc123:status
> 
> and another question, is it ok to model the 'start' and 
> 'stop' actions as 'action' resources?
> 
> so, POST to http://example.org/openQRM/actions/start with data
> http://example.org/openQRM/service/abc123
> 
> thanks,
> ittay
> 
> Ittay Dror wrote:
> > 
> > 
> > thanks for your help.
> > 
> > one final question, is it ok to model the API for 'status' as 
> > http://example. org/openQRM/ service/abc123# status 
> > <http://example.org/openQRM/service/abc123#status> (thus 
> stating more 
> > clearly it is a property of the service, and not a resource 
> in itself)
> > 
> > thanks,
> > ittay
> > 
> > John D. Heintz wrote:
> >  >
> >  >
> >  > Hello Ittay,
> >  >
> >  > Here's how I would approach the problem by way of small example. 
> > I've  > used "====..." just to help with the formatting.
> >  >
> >  > The first thing I would do is break down the name/uri 
> space like this:
> >  > ============ ===
> >  > GET http://example. org/openQRM/ service/abc123  > 
> <http://example. 
> > org/openQRM/ service/abc123 
> > <http://example.org/openQRM/service/abc123>>
> >  > ============ ===
> >  > HTTP/1.1 200 OK
> >  >
> >  > <?xml version="1.0" encoding="utf- 8"?>  > ...
> >  > <service name="..." status="started" ...
> >  > ============ ===
> >  >
> >  > This indicates that we can get a representation of the 
> service  > 
> > identified by "abc123".
> >  >
> >  > We could then PUT or POST a modifed representation with  > 
> > status="stopped" , but I'll take a different approach. 
> Let's have the  
> > > represenation provide more information via the hypertext:
> >  >
> >  > ============ ===
> >  > GET http://example. org/openQRM/ service/abc123  > 
> <http://example. 
> > org/openQRM/ service/abc123 
> > <http://example.org/openQRM/service/abc123>>
> >  > ============ ===
> >  > HTTP/1.1 200 OK
> >  >
> >  > <?xml version="1.0" encoding="utf- 8"?>  > ...
> >  > <service name="..." ...
> >  > <status current="started" href="abc123/ status" ...
> >  > ============ ==
> >  >
> >  > Now we have marked a new URI that is specially designed for the 
> > status  > of the "abc123" service.
> >  >
> >  > From that URI:
> >  > ============ ===
> >  > GET http://example. org/openQRM/ service/abc123/ status  > 
> > <http://example. org/openQRM/ service/abc123/ status 
> > <http://example.org/openQRM/service/abc123/status>>
> >  > ============ ===
> >  > HTTP/1.1 200 OK
> >  >
> >  > started
> >  > ============ ===
> >  >
> >  > Let's say that we want to support a simple PUT on this 
> resource to  
> > > enable changing the state of a service:
> >  >
> >  > ============ ===
> >  > PUT http://example. org/openQRM/ service/abc123/ status  > 
> > <http://example. org/openQRM/ service/abc123/ status 
> > <http://example.org/openQRM/service/abc123/status>>
> >  >
> >  > stopped
> >  > ============ ===
> >  > HTTP/1.1 200 OK
> >  >
> >  > stopped
> >  > ============ ===
> >  >
> >  > If ours was the only client controlling that service 
> this would be  
> > > perfectly clear, but other clients (or the service itself) might 
> > have  > already changed the status. Let's add some details that 
> > provide us with  > information to do that.
> >  >
> >  > ============ ===
> >  > GET http://example. org/openQRM/ service/abc123/ status  > 
> > <http://example. org/openQRM/ service/abc123/ status 
> > <http://example.org/openQRM/service/abc123/status>>
> >  > ============ ===
> >  > HTTP/1.1 200 OK
> >  > Last-Modified: Tue, 09 Jan 2007 22:34:37 GMT  > ETag: "xyz-789"
> >  >
> >  > started
> >  > ============ ===
> >  >
> >  > The Last-Modified should be clear, the ETag is a 
> server-side hashed 
> > id  > that can encode details like identity and version 
> number. In our  
> > > subsequent PUT we can indicate to only do the work if the 
> resource 
> > still  > matches what we last saw (optimistic locking).
> >  >
> >  > ============ ===
> >  > PUT http://example. org/openQRM/ service/abc123/ status  > 
> > <http://example. org/openQRM/ service/abc123/ status 
> > <http://example.org/openQRM/service/abc123/status>>
> >  > If-Modified- Since: Tue, 09 Jan 2007 22:34:37 GMT  >  > 
> stopped  > 
> > ============ ===  > HTTP/1.1 200 OK  >  > stopped  > 
> ============ ===  
> > >  > Now it's safe for us to assume that "we" are the agent 
> that did 
> > stop the  > service. A failure response would have been returned if 
> > not.
> >  >
> >  > Stuff that I've ignored so far:
> >  > * content type: I'm just typing anything for example. 
> Should always  
> > > prefer standard and interoperable content types.
> >  > * content negotiation: browsers and B2B agents may not want the 
> > same  > representation content types  > * Forms: How does 
> this agent 
> > know it can PUT to that resource? What  > values are allowed to be 
> > sent?
> >  > * probably a bunch more, I hope others jump in to 
> correct me ;)  >  
> > > Hope this helps provide a more clear example of the differences.
> >  >
> >  > John
> >  >
> >  > On 1/9/07, *Ittay Dror* < ittayd@qlusters. com  > 
> > <mailto:ittayd@qlusters. com <mailto:ittayd%40qlusters.com>>> wrote:
> >  >
> >  > what troubles me is that most examples i find to explain 
> rest use  
> > > simple cases, where no logic is actually running, and so 
> it is easy  
> > > to transfer services to properties (since the services do very 
> > little)  >  > so here is my real world use case: openQRM is 
> a platform 
> > for  > provisioning and managing services in a DC. a service is an 
> > entity  > named VirtualEnvironment that encapsulates both a set of 
> > policies on  > how to provision and manage the real service and a 
> > capture of the  > real service's state (resources, 
> utilization, error, 
> > etc.)  >  > we can do many actions on a service, but the 
> primary ones 
> > are to  > start and stop it. starting means resources are selected 
> > from a pool  > and assigned to work for the service, the 
> software is 
> > deployed on  > them and the service is monitored. stopping is the 
> > reverse.
> >  > obviously openQRM does all this. the client just 
> requests to 'start'
> >  > or 'stop'.
> >  >
> >  > now, it is hard for me to see 'start' and 'stop' as 
> values of the  
> > > 'currentactivity' property. if anything, it looks like a 
> masquerade  
> > > of the RPC equivalent of posting to the 
> VirtualEnvironment entity  > 
> > with the pair 'action=start' .
> >  >
> >  > thank you for your help,
> >  > ittay
> >  >
> >  > wahbedahbe wrote:
> >  > >
> >  > >
> >  > > Hmmm. I'm a bit of a newbie too but let me take a stab 
> at this as 
> > an  > > exercise.
> >  > >
> >  > > Now let me first say that the way you posed the 
> question is very  
> > > > "objecty" or "servicey" to begin with and makes it a 
> bit hard to  
> > > > answer. You've basically said "I have a service with 
> methods A,  > 
> > B, and  > > C; how do I make it resource based?" The 
> problem is that 
> > REST has no  > > concept of class-specific methods, so 
> without knowing 
> > what A, B,  > and C  > > do, its hard to answer your question. In 
> > short, there is no straight  > > forward transformation of 
> an abstract 
> > service to abstract resources.
> >  > > (At least not that I know of...) They are two very 
> different ways 
> > of  > > modeling the interface. I can't transform one type 
> of solution 
> > to  > > another without understanding the problem.
> >  > >
> >  > > But I can infer a bit about the problem from the fact you are 
> > using  > > the concept of a person and things a person can do (eat, 
> > sleep,  > work).
> >  > > I'll assume here that sleep() and work() change the 
> state of the  
> > > > person (to sleeping and working respectively) . Maybe 
> there is a  
> > > > substate when working that says what work you are doing. Let's 
> > also  > > assume that eat() adds some food items to a list 
> of things eaten.
> >  > >
> >  > > So to work (on building a bike shed):
> >  > > PUT /person/ittay/ currentactivity  > > Content-Type: 
> > application/ x-activity+ xml  > >  > > <activity>  > > <type>work</ 
> > type>  > > <sub-type>building a bike shed</sub-type>  > > 
> </activity>  
> > > >  > > To sleep:
> >  > > PUT /person/ittay/ currentactivity  > > Content-Type: 
> > application/ x-activity+ xml  > >  > > <activity>  > > <type>sleep< 
> > /type>  > > </activity>  > >  > > To eat an apple:
> >  > > POST /person/ittay/ stomach
> >  > > Content-type: application/ x-food+xml  > >  > > <food>apple< 
> > /food>  > >  > > Now these actions could also kick off related 
> > business processes. I  > > think the only method that can't is GET. 
> > Note that you could use get  > > to retrieve the current 
> activity from 
> > /person/ittay/  > currentactivity or  > > the list of things eaten 
> > from /person/ittay/ stomach.
> >  > >
> >  > > --- In rest-discuss@ yahoogroups. com  > > <mailto: 
> rest-discuss% 
> > 40yahoogroups. com  > <mailto:rest- discuss%40yahoog roups.com> >, 
> > Ittay Dror <ittayd@...>
> > wrote:
> >  > > >
> >  > > > thanks for your example and site reference.
> >  > > >
> >  > > > i did know that i use only HTTP methods, what i 
> lacked is how 
> > to  > > model my business methods. i am a newbie at this (maybe i 
> > should have  > > indicated that)  > > >  > > > may i impose with a 
> > followup?
> >  > > >
> >  > > > say i have a person entity in my application. this 
> entity has  
> > > > several business methods (eat, sleep, work). how should 
> i model a  
> > > rest  > > api for these? create a PersonManager resource 
> (which then 
> > will need  > > to accept as argument what action to do), or create 
> > resources per  > > action (/person/ittay/ eat maybe?).
> >  > > >
> >  > > > thanks,
> >  > > > ittay
> >  > > >
> >  > > > Jan Algermissen wrote:
> >  > > > > Hi Ittay,
> >  > > > >
> >  > > > > the kind of question you ask indicates that you 
> have no yet  
> > > > understood a fundamental aspect of REST, namely that 
> there is a  > 
> > > uniform interface. You do not get any other methods as the  > 
> > uniform set  > > (the HTTP methods in the case of using HTTP as an 
> > architecture)  > > > >  > > > > Without any intention to be rude, I 
> > suggest you take a while to  > > read through some of the REST 
> > material out on the Web (the REST wiki  > > at http://rest 
> > <http://rest>. blueoxen. net <http://rest.
> >  > blueoxen. net <http://rest. blueoxen. net 
> > <http://rest.blueoxen.net>>> is a good  > > starting point as is 
> > Paul's site  > > at http://prescod. com/rest < http://prescod. 
> > com/rest  > <http://prescod. com/rest 
> <http://prescod.com/rest>>> ). 
> > This will help  > > in future discussions.
> >  > > > >
> >  > > > >
> >  > > > >> Should I use 'POST' with a 'method=build' 
> parameter to the  
> > > 'plan'
> >  > > URI?
> >  > > > >
> >  > > > > No, this is about the worst from a REST POV as it 
> is hidden RPC.
> >  > > > >
> >  > > > > Think along these lines:
> >  > > > >
> >  > > > > Provide a means for clients to pick a resource 
> that behaves 
> > the  > > way they are interested in (some hypermedia the 
> clients come 
> > accross  > > could declare a resource as a BuildingManager) 
> and then 
> > use POST to  > > submit the building plan.
> >  > > > >
> >  > > > > POST /BuildingManager
> >  > > > > Content-Type: application/ blueprint <-- this type is  > > 
> > fictous; it would need to be standardized within the realm 
> of  > your 
> > system  > > > >  > > > > <blueprint>  > > > > <wall 
> location=".. .."/>  
> > > > > > </blueprint>  > > > >  > > > >  > > > > IOW, in a RESTful 
> > system clients late-bind to resources based on  > > 
> runtime-declared 
> > abstract bahavior of those resources and they  > > 
> communicate via a 
> > fixed set of methods.
> >  > > > >
> >  > > > > HTH,
> >  > > > >
> >  > > > > Jan
> >  > > > >
> >  > > > >
> >  > > > >
> >  > > > >
> >  > > > >
> >  > > > >> Thanks,
> >  > > > >> Ittay
> >  > > > >>
> >  > > > >>
> >  > > > >>
> >  > > > >>
> >  > > > >> Yahoo! Groups Links
> >  > > > >>
> >  > > > >>
> >  > > > >>
> >  > > > >>
> >  > > > >>
> >  > > > >
> >  > > >
> >  > > >
> >  > > > --
> >  > > > ============ ========= ========= =====  > > > Ittay 
> Dror,  > > 
> > > Chief architect,  > > > R&D, Qlusters Inc.
> >  > > > ittayd@...
> >  > > > +972-3-6081994 Fax: +972-3-6081841  > > >  > > > 
> www.openqrm. 
> > org - Data Center Provisioning  > > >  > >  > >  >  >  > --  > 
> > ============ ========= ========= =====  > Ittay Dror,  > Chief 
> > architect,  > R&D, Qlusters Inc.
> >  > ittayd@qlusters. com <mailto:ittayd@qlusters. com 
> > <mailto:ittayd%40qlusters.com>>  > +972-3-6081994 Fax: 
> +972-3-6081841  
> > >  > www.openqrm. org <http://www.openqrm. org 
> > <http://www.openqrm.org>> - Data Center Provisioning  >  >  >  > 
> > Yahoo! Groups Links  >  >  > (Yahoo! ID required)  >  > 
> mailto:rest- 
> > discuss- fullfeatured@ yahoogroups. com  > <mailto:rest-discuss- 
> > fullfeatured@ yahoogroups. com 
> > <mailto:rest-discuss-fullfeatured%40yahoogroups.com>>
> >  >
> >  >
> >  >
> >  >
> >  >
> >  >
> >  > --
> >  > John D. Heintz
> >  > Principal Consultant
> >  > New Aspects of Software
> >  > Austin, TX
> >  > (512) 633-1198
> >  >
> > 
> > --
> > ============ ========= ========= ===== Ittay Dror, Chief architect, 
> > R&D, Qlusters Inc.
> > ittayd@qlusters. com <mailto:ittayd%40qlusters.com>
> > +972-3-6081994 Fax: +972-3-6081841
> > 
> > www.openqrm. org - Data Center Provisioning
> > 
> > 
> 
> 
> --
> ===================================
> Ittay Dror,
> Chief architect,
> R&D, Qlusters Inc.
> ittayd@...
> +972-3-6081994 Fax: +972-3-6081841
> 
> www.openqrm.org - Data Center Provisioning
> 
> 
>  
> Yahoo! Groups Links
> 
> 
> 

On 1/10/07, Bill Venners <bv-svp@...> wrote:
>
> What do you mean by "in theory structured path segments allow more
> versatile delegation of authority?"

URIs are hierarchical. The "/" character is a delimiter. For example,
examine which URLs automatically receive HTTP Basic auth credentials
after an initial 401 response from

http://example.com/foo/bar/baz

vs.

http://example.com/foo/bar;baz

> Also, I personally am not sure whether semicolon separated params
> would be prettier or uglier than traditional query params.

Pretty paths are mapped to ugly query parameters, so there is no need
to dwell on the relative merits. To use the first example from
http://routes.groovie.org/manual.html#route-path

http://example.com/myapp/feeds/electronics/atom.xml

maps to

http://example.com/myapp?controller=feeds&category=electronics&action=atom&type=xml

Of course, that is just one concrete example. It turns out that the
commonly used parts of URI syntax are flexible enough to accommodate a
rule-based mini language for routing. The rest of it hasn't been
necessary yet, aside from implementation-specific uses. So, who cares
if Tomcat breaks the semicolon? You can always use something less
broken.

-- 

Robert Sayre

"I would have written a shorter letter, but I did not have the time."

Jon Hanna wrote: 
> Mike Schinkel wrote:
> > Well, I want to explore why it is harder for search engines to find 
> > that page. And can we change that? Or consider the problem from a 
> > different perspective?
> 
> This is simple. The search engine finds x pages which it 
> deems equally good as a response to a given query. Which does 
> it link to first? There's no way of saying.

You didn't answer "can we change that?" 

> > Google tweaks their algorithms quarterly. Why could they 
> not include an update given new guidance? The rest would 
> follow.
> 
> We can already give this guidance to Google. Google reacts 
> appropriately when it receives a 301 Moved Permanently by 
> treating the target of the location header as the URI to use.

That is much like we are in a city planning meeting where I say "People need
a bus to Harold's Cross" to which you say "Tell them to take a train" to
which I say "There isn't a train that goes to Harold's Cross" to which you
reply "Tell them to take a train" ...

The point is giving Google a 301 requires the page to be redirected when I
explicitly stated that redirection is not appropriate for the use-case and
in that use-case redirection would confuse users.  

One option might be to return a 203 Non-Authoritative Information with
Content-Location pointing to a (more) canonical URL, but I'm certainly not
the expert on the uses of return code and http headers so I don't know if
this would be misusing that information or not. Can anyone tell me if this
would be a viable use to indicate a canonical URL w/o redirecting the client
to the canonical URL?

> > It is also a caching minus, because the cache won't 
> > know it already has something that came via a different 
> > URI. That can be a usability minus in the form of slower 
> > perceived response time, and a business minus in terms 
> > of higher bandwidth costs.
> > 
> > Again, I'd like to explore why that is and see if there are 
> > not new ways to look at the problem.
> 
> The same reason you don't know whether what's behind 
> door number 1 is the same as what's behind door number 2.

That may be why, but it doesn't explore new ways of looking at the problem.

> Again, but a note behind door number 2 saying "go to door 
> number 1 and open that instead" and your problem is solved. 
> As a bonus we can also control how often we check door number 
> 2 to see if that note is still there.

Again, you are giving me licorice ice cream after I told you I don't like
licorice simply because all you have is licorice.  It doesn't get me ice
cream that I can stand to eat.

> Mike Schinkel wrote:
> > Also, I just ran across this:
> > http://www.w3.org/QA/2004/08/readable-uri
> 
> Being treated as opaque does not mean it can't be readable or 
> respond well to guesswork.

I didn't say it did.

> Mike Schinkel wrote:
> > For one example, look at Wikipedia's URLs; is it a wonder there are 
> > linked as often at they are?
> > 
> > http://en.wikipedia.org/wiki/REST
> > 
> > IF it were instead
> >
> http://www.wikipedia.org/topic.php?topicID=7937521&lang=en-US&
> > source-ie7&en-US&ie=utf8&oe=utf8
> > 
> > I can guarantee you it would not be linked as much.
> 
> If one 301'd to the other then the benefits you suggest are 
> there would still hold.

Not at all, you are thinking of different use-cases than I.  Consider
someone is writing a topc on their blog and use the terms "REST", "HTTP",
"HTML", "URL", "URI", "AJAX", "Javascript", etc. They want to hyperlink
those terms to definitions. Given Wikipedia's clean and clear URL structure,
they know that they can link to "http://en.wikipedia.org/wiki/REST",
"http://en.wikipedia.org/wiki/HTTP", etc. and so they do it.  

But let's assume that Wikipedia only offered the "ugly" URL structure I
described above. The author would often think to themselves "Damn, it's just
too much trouble to link to all those terms. So I'm just not going to.  Let
the user Google them themselves if they want to know what they mean."  And
in that case their post has less value for readers and adds less to the web
overall.

Of course you might say "They can just hyperlink to Google with
'http://www.google.com/search?q=REST', etc.", but then if Google's URL
structure were not easy to grok, that wouldn't be possible without a lot
more work either, so if you suggested that you'd just be helping me make my
point.

> > And when people link a site, the benefits acrue to the site.
> 
> There are more benefits in people linking to one page on your 
> site than 15 equivalent pages.

Currently yes, but I'm not talking about the current state of the web, I'm
talking about an exploration for improving it.  Many people told TimBL that
the concept of the web itself made no sense, but that didn't stop him. I'm
not suggesting my ideas are on par with Tim's; but I am suggesting that
impeding the exploration of improvements will increase the likelihood that
no improvements will be seen.

As an aside, it never ceases to amaze me how many people are willing to
proactively debate away attempts to improve the web and make it more
usable...

> > So you see, there as so many small reasons why 
> > well designed URLs are a benefit. But if you don't 
> > drill down to see those ways, it doesn't seem
> > like much at 50,000 feet.
> 
> The benefits of well-designed URIs is a different matter to 
> the benefits of canonical URIs. 

I agree, but I'd like to explore if it is possible that they are not at odds
either.

> > 5.) Further, the URI Opacity concern is related to *machines*, not 
> > humans because humans have an error correcting mechanism called 
> > intelligence. If they go to the "/cart/" URL and it displays 
> > information about wheelbarrows instead of a shopping cart, 
> > the human can figure it out and continue looking. The machine is 
> > yet to be capable until programmed in advance for that problem.
> 
> No, the opacity concern is related to humans because if they 
> phone and complain that they got information about 
> wheelbarrows when they should have gotten a shopping cart I'm 
> going to want to hit someone (not really, I get far worse 
> calls than that, but they do make me want to hit someone). 
> This is because humans have an error-generating mechanism 
> called stupidity.

Do you really think your fellow humans are less intelligent then you? I
think you are just voicing the frustation of someone who has been on the
support line for a poorly designed system.  

On the contrary, one of the reasons humans phone and complain that they got
information about wheelbarrows when they should have gotten a shopping cart
is because the designer of the shopping cart decided that making the URLs
understandable by humans was either not worth his effort or believed that
users couldn't possibly understand URLs, which is a very arrogant position
to take.  People didn't understand automobile controls, postal codes,
telephone numbers, automated teller machines, and more when they were first
introduced, but now the vast majority of people get on fine with them. The
same will be true of URLs as time passes.

> Responding reasonably to guesswork is great. I strive to 
> design URI schemes as intuitively as I can. But I will delete 
> any bug report about guessed URIs not working ...

And I would agree that that is an appropriate position. OTOH, if I learned
that people frequently entered "http://www.mysite.com/buynow/" and got a
broken link, I can tell you I'd go to the effort to ensure they got what
they were seeking, and all pedantics aside, I bet you would too. ;-)

> unless its very 
> definitely marked as a suggested enhancement.

However, I didn't understand what you meant by this.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

Walden Mathews wrote: 
> : For one example, look at Wikipedia's URLs; is it a wonder 
> there are linked
> : as often at they are?
> :
> : http://en.wikipedia.org/wiki/REST
> :
> : IF it were instead
> :
> : 
> http://www.wikipedia.org/topic.php?topicID=7937521&lang=en-US&
source-ie7&en-
> : US&ie=utf8&oe=utf8
> :
> : I can guarantee you it would not be linked as much.  I 
> could remember and
> : compose the former, there is no way I could remember the 
> latter (FYI, I
> : frequently like to Wikipedia just by prefixing a term with
> : "www.wikipedia.org/wiki/")
> 
> 1. I can tell you are in sales.

Why the ad-hominem response?  

Anyway, we are all in sales. Parents sell their children on eating
vegetables, scientists sell sponsors on funding their research and
colleagues on supporting their findings, standards participants on agreeing
their to positions on a proposed standard, job interviewees on themselves,
etc. Anyone who doesn't believe there are in sales are just fooling
themselves and are most likely less effective then they could otherwise be.

That said, "Have I every really been in sales?"  Well, I've never held a job
with the word "sales" in the title. I've never received a paycheck that
included any sales commissions. But have a ever sold something that a
company I was running needed me to sell?  Absolutely.

> 2. You make assumptions I don't: have you heard of cut and paste?

Actually, your assumptions are broader than mine; you are assuming there is
only one use-case when there are many. See my reply to Jon Hanna [1] with
specifics of the use case I was describing.

> : If I'm at a party and someone asked me about some pictures 
> I took, I can
> : just tell them to go to:
> :
> : http://www.flickr.com/photos/mikeschinkel
> :
> 
> I guess if they can remember that, several hours and several 
> beers later, then they can probably also remember your name.  
> That's better than I can do.

Not at all. All they need to do is be able to read my writing on the back of
my business card. But that's only because Flickr has a URL that I can
remember; if it didn't I wouldn't have been able to remember it in order to
write in on the back of my business card.

BTW, this is not hypothetical; I have given out this URL when I've told
friends that I had pictures they were interested in.

> Typically, I email or IM links to people.  As far as typing 
> into the location bar of the browser, I avoid it like the plague.

Unfortunately, most of the web-using world's population isn't tethered 100%
of the time to a machine capable of sending email.

> : I share an appreciation for motorcycles with my dad.  
> : I like to send him links in email. Let's assume the link 
> : breaks. Which one is he likely to be able to fix? (and 
> : which one is least likely to break?)
> 
> Breaks?  You mean line breaks?  Yes, I agree with 
> *short* URI in principle.

Yes, sorry for my typo.

> : But if they were this instead this, it would be much 
> : easier for dad to identify and fix those broken links 
> : (and much less likely they'd break):
> 
> I feel bad for your dad 

Don't be, he is happy that his son shares one of his interests and that his
son communicates with him so often. Many fathers could only wish for the
same.

> in this case, and if I were he, I'd  stick to fixing 
> motorcycles, because it would entail much 
> less futile typing.

That's a rather arrogant response, and is not appreciated.

> Honestly, Mike, show your dad how to cut and paste broken (line
> wrapped) URI back together.  

I have shown him. But I can't show the untold millions of other people's
fathers, or mothers, how to do the same. 

> : Now, let's say that I wanted to send him a link to look at the 50th
> : Anniversary Sportster. See the link below? Tell me what I 
> should send him.
> : Go head. Open it up. And tell me what link.
> 
> I'm afraid....

As you should have been. :-)

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

[1] http://tech.groups.yahoo.com/group/rest-discuss/message/7549

Nic James Ferrier wrote:
> > I made an assumption in my comments which you 
> > ferreted out; that yes I was talking about defaults 
> > where users of proxies and firewalls who barely have 
> > the skills (or the money) to get them up and running, 
> > let alone optimize them. With many organizations, 
> > even large one, use the same "Jell-O" model [1] for 
> > infrastructure configuration as some companies use 
> > for shipping software; when it stops quivering it's 
> > done!
> > 
> > OTOH, Nic was speaking about the large organizations 
> > where one departments often didn't care about the 
> > concerns of others.
> 
> I think Elliotte is correct that we could fix the problem by 
> getting the proxy makers to change their proxies.
> 
> However, how long would it take to fix the problem. The big 
> organization that I was referring to had (amongst others) a 
> Novell Netware proxy server. It was at least 10 years old.
> 
> I recently made a trip to a medium sized company who were 
> still using Microsoft Proxy Server 1.0. I don't even want to 
> think about how old that is.

Damn!  I knew I forgot to address that one point. :)  But no need, as your
comments covered it perfectly; we can fix it for new equipment but installed
equipment will take years if not over a decade to rotate out of use...

> > Indeed all you may need to do when a customer tells 
> > you your system seems broken is say, "Oh, you're using 
> > proxy X? That's broken and non-spec compliant. Use 
> > proxy Y instead and all will be fine."
> >
> > That's fine, assuming that information gets to the right 
> > person in the company (which is a huge assumption) and 
> > that the right person doesn't have other tasks they view 
> > as higher priority (which is another big assumption.)
> 
> I agree Mike. It's often really difficult to find out what is 
> actually causing the problem. Unless you have network access 
> to the client site in question it's almost impossible.
> 
> And Elliotte's assertion doesn't work at all if we're talking 
> about a web 2.0 business like digg or flikr. If those sites 
> used PUT and it failed for everyone nehind a crappy proxy 
> just how many of those failures would get reported to them?

That's a great point I hadn't thought to make; if a company is selling
expensive services (something like a Salesforce.com), customers will fix
problems for them. But users will just give up on free high volume web 2.0
sites like digg and flickr w/o even letting them know...

> > Unfortunately, only people who are drawn to the technology for 
> > personal interest see this as important enough to allow it 
> > to affect other factors. For another perspective on this, ask 
> > the WHATWG editor Ian Hickson if 
> > he thinks browser vendors will support standards that could 
> > potentially minimize their marketshare in any way.[2]  Almost no 
> > company will be willing to limit it's marketshare for a technical 
> > ideal. The way to achieve the technical ideal on as broad basis as 
> > possible is to make that support painless, not by ignoring market 
> > realities with the claim that "it is the right thing to do 
> > for the greater good."
> 
> Spec compliance happens in the end. It just takes a long time.

Agreed. But you and are both agree that business as got to be done in the
mean time.

> Of course, it would help if broken and rubbish 
> implementations didn't get so widespread in the first place. 
> But that's to do with the ridiculous amounts of hype that 
> drives our industry.

hehe.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Mark Baker wrote:
> On 1/9/07, Mike Schinkel <mikeschinkel@...> wrote:
> > However, the reason I was asking was because I was trying 
> > to gather evidence to present to Ian Hickson to support adding 
> > URI Template support to the action method of the form element 
> > in Web Forms 2.0.  I sent an email to uri@... to that 
> > effect[1], but got to response.
> 
> Though in theory that sounds like a great idea, it would 
> break existing clients which is a non-starter when defining 
> HTML extensions.  

Excellent point!  I hadn't considered that.  Duh.

> You'd need a new parameter to get 
> around that problem.

So by "parameter" do you mean attribute?  For example, would this be
workable where newer browsers would use "template" instead of "action?"

	<form method="get"
		action="http://www.welldesignedurls.org/query">
	
template="http://www.welldesignedurls.org/{category}/{era}/">
		<p>Where would you like to go?
			<select name="category">
				<option value="standards">Standards</option>
				<option value="proposals">Proposals</option>
				<option value="ideas">Ideas</option>
			</select>/<select name="era">
				<option value="past">Past</option>
				<option value="present">Present</option>
				<option value="future">Future</option>
			</select>
			<button type="submit">Go!</button>
		</p>
	</form>

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Hi,

the software I'm working on has a GET/PUT-interface for its
configuration. GETting answers an XML document of the active
configuration, PUTting a new one causes the server to reconfigure its
mode of operation.

I like the model and I hope adminstrators will like the
curl-vi-curlMinusT cycle.

However, does someone know of a browser plugin that could make this even
nicer? Something that offers an edit button and an option to PUT the
edited document? All my online searches have been to no avail.

Thanks
Matthias

-- 
Matthias Ernst
Software Architect
 
tel +49.40.32 55 87.503
fax +49.40.32 55 87.999
matthias.ernst@...

Mike Schinkel wrote:

> I believe that the market doesn't care about that level of detail, only
> academics and standard committees care to that extent. I believe the market
> cares about what works for them to achieve their specific goals.

I understand what you're saying, but I don't think you got me. In this 
case it is my contention that following the specifications leads to 
greater efficiency and greater profits. Companies so incompetent that 
they cannot manage a firewall or proxy server will be beaten by 
companies that can. Precisely because the market prefers competent, 
profitable, efficient companies, the pointy-haired will be weeded out.

We're not advocating following the spec for the spec's sake. We're 
advocating following the spec because it works better than not following 
it.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Elliotte Harold wrote:
> Mike Schinkel wrote:
> > I believe that the market doesn't care about that level of detail, 
> > only academics and standard committees care to that extent. 
> > I believe the market cares about what works for them to 
> > achieve their specific goals.
> 
> I understand what you're saying, but I don't think you got 
> me. In this case it is my contention that following the 
> specifications leads to greater efficiency and greater 
> profits. Companies so incompetent that they cannot manage a 
> firewall or proxy server will be beaten by companies that 
> can. Precisely because the market prefers competent, 
> profitable, efficient companies, the pointy-haired will be weeded out.
> 
> We're not advocating following the spec for the spec's sake. 
> We're advocating following the spec because it works better 
> than not following it.

I generally agree with you in the long term, but not in the short term. The
market won't reward many companies fast enough, so we have the chicken & egg
problem.  If they did reward them quickly, we'd have no problem with people
not following standards, right?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

P.S. I just read your article [1] and was very excited by it. I think you
will like a concept I'm working on when I am finally ready to publish on
it...

[1] http://cafe.elharo.com/web/rest-is-like-quantum-mechanics/

Ernst, Matthias schrieb:
> 
> 
> Hi,
> 
> the software I'm working on has a GET/PUT-interface for its
> configuration. GETting answers an XML document of the active
> configuration, PUTting a new one causes the server to reconfigure its
> mode of operation.
> 
> I like the model and I hope adminstrators will like the
> curl-vi-curlMinusT cycle.
> 
> However, does someone know of a browser plugin that could make this even
> nicer? Something that offers an edit button and an option to PUT the
> edited document? All my online searches have been to no avail.
> 
> Thanks
> Matthias

Some time ago I was thinking about making a Firefox extension for that 
(+ some WebDAV features). Back then, I couldn't manage to retrieve the 
binary content using the XmlHttpRequest object, so I gave up.

Best regards, Julian

Amaya has PUT support.

On 1/10/07, Ernst, Matthias <matthias.ernst@...> wrote:
> Hi,
>
> the software I'm working on has a GET/PUT-interface for its
> configuration. GETting answers an XML document of the active
> configuration, PUTting a new one causes the server to reconfigure its
> mode of operation.
>
> I like the model and I hope adminstrators will like the
> curl-vi-curlMinusT cycle.
>
> However, does someone know of a browser plugin that could make this even
> nicer? Something that offers an edit button and an option to PUT the
> edited document? All my online searches have been to no avail.
>
> Thanks
> Matthias
>
> --
> Matthias Ernst
> Software Architect
>
> tel +49.40.32 55 87.503
> fax +49.40.32 55 87.999
> matthias.ernst@...
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Mike Schinkel wrote:

> I generally agree with you in the long term, but not in the short term. The
> market won't reward many companies fast enough, so we have the chicken & egg
> problem.  If they did reward them quickly, we'd have no problem with people
> not following standards, right?

Markets are not perfectly efficient. There's always friction. It takes 
time for the bad actors to be weeded out, but the time does pass.

When I started working with HTML it seemed like forever before people 
could use forms reliably. When I started working with CSS, it seemed 
like anything beyond a font tag would never be possible. When I started 
working with XML, I despaired of using XSLT on public facing web sites. 
All these are now reasonably reliable today; even if most developers 
still assume it's 1999 and that none of these things work. (Well, maybe 
not forms. :-) )

Funny how time passes faster as I get older. :-)

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Bill Venners wrote:
> In observing my own behavior while using other people's web 
> sites, I noticed I occasionally find myself hacking off 
> pieces of a URI in the hopes of finding something 
> conceptually higher up in the hierarchy.  
> It usually didn't work, but I tried. I did not add things to 
> URIs, but I did try to subtract things. I want URI hacking 
> that to always work at the websites whose URIs and 
> information architecture I design. Where I depart from Mike's 
> approach is that I would still pick one hierarchy from his 
> many possibilities, and have one canonical URI for each resource.

I'm starting to come to the conclusion that the resources I think are the
same are actually different. Yes, they may have mostly the same content but
they have different breadcrumbs which mean one can't be cached and served
for the other. Of course someone might argue that because the content on the
different pages is so similar I should not create different resources; I
should only have one. But I think that would be being pedantic in trying to
optimize the caching benefit in exchange to the detriment of usability.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

> Webarch [1] is pretty clear on the topic, though. Agents 
> should not infer properties from the URI, and "agents" 
> means both people and machines.

However, metaDataInURI-31 [2] which was finalized more recently than
WebArch[1] and was also referenced in WebArch is also very clear on the
topic:

	2.2 Guessing information from a URI
	...the ability to explore the Web informally and experimentally is
very 
	valuable, and Web users act on such guesses about URIs all the time.

	Many authorities facilitate such flexible use of the Web by
assigning 
	URIs in an orderly and predictable manner. Nonetheless, in the
example 
	above, Bob is responsible for determining whether the information 
	returned is indeed what he needs.

Is it possible that we have an ingrained view of URI Opacity that is
struggling with its evolvotion towards a more realistic and open-minded
stance?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/

"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

[1] http://www.w3.org/TR/webarch/#uri-opacity 
[2] http://www.w3.org/2001/tag/doc/metaDataInURI-31#guessing
 

Chuck Hinson said:
> And if I understand Roy[1] correctly, the only constraint is 
> that agents should not INFER properties from the URI. As 
> long as things are explicitly defined (by spec, by the server, 
> or otherwise), agents can and do make use of information 
> embedded in the URI.

THANKS for the link. I've been trying to locate it for a while.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

[ Attachment content not displayed ]

Jon Hanna wrote:
> It's a foolish user though that can't tell the difference 
> between a guess they tried and "the way things are 
> meant to be".
 
Can you please clarify your context for "the way things are meant to be?"  I
don't follow.
 

-- 
-Mike Schinkel 
http://www.mikeschinkel.com/blogs/ 
http://www.welldesignedurls.org/ 
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Walden Mathews wrote:
> 1. You train your user to use the system at full leverage.
 
Can you clarify what you mean by "full leverage."
 
> 2. You retain encapsulation of your implementation, 
> and are then free to change it without breaking your 
> clients.
 
Giving users the ability to manually hack or guess URLs does not constrain
you from changing in the future (although, "Cool URIs don't change"...)
Users who hack or guess URLs in a manual mode do so almost exclusively right
after retrieving an existing resource.  And if a URL changes that they used
to go to, they are human, they will adjust.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Bill Venners wrote:
 
> A agree he should present the information architecture 
> through hypertext, but it need not be "instead." It can 
> be in addition to presenting it in the URI. Like it or not, 
> both the hypertext and the URI are part of the user 
> interface of a web application.

That is a key and vital point, and definitely worth repeating.


-- 
-Mike Schinkel 
http://www.mikeschinkel.com/blogs/ 
http://www.welldesignedurls.org/ 
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Mike,

In wikis by http://www.jot.com/ (recently acquired by Google), each
page has one and only one canonical URL. However, users can construct
almost any path to get to the canonical URL, and if all the pages
along the path exist, the wiki will show them the page they want.

So in this case, canonical URLs work very nicely with user URL-hacking.

Is that something like what you have in mind?

Mike Schinkel wrote:
 > Jon Hanna wrote:
 >> It's a foolish user though that can't tell the difference
 >> between a guess they tried and "the way things are
 >> meant to be".
 >
 > Can you please clarify your context for "the way things are meant to 
be?"  I
 > don't follow.

If I'm at http://www.examplenet/a/b/c and go to 
http://www.examplenet/a/b/ and receive a 403 or anything else I don't 
assume the application is buggy.

Hi Mike,

On Jan 10, 2007, at 6:27 AM, Mike Schinkel wrote:

> Bill Venners wrote:
>> In observing my own behavior while using other people's web
>> sites, I noticed I occasionally find myself hacking off
>> pieces of a URI in the hopes of finding something
>> conceptually higher up in the hierarchy.
>> It usually didn't work, but I tried. I did not add things to
>> URIs, but I did try to subtract things. I want URI hacking
>> that to always work at the websites whose URIs and
>> information architecture I design. Where I depart from Mike's
>> approach is that I would still pick one hierarchy from his
>> many possibilities, and have one canonical URI for each resource.
>
> I'm starting to come to the conclusion that the resources I think  
> are the
> same are actually different. Yes, they may have mostly the same  
> content but
> they have different breadcrumbs which mean one can't be cached and  
> served
> for the other. Of course someone might argue that because the  
> content on the
> different pages is so similar I should not create different  
> resources; I
> should only have one. But I think that would be being pedantic in  
> trying to
> optimize the caching benefit in exchange to the detriment of  
> usability.
>
That's a good point. Caching is valuable too from a usability  
perspective and a business one, because it will make the site seem  
faster to users. I can think of a few options in that case.

One is to let go of the breadcrumbs. Users can use the back button to  
back up. On Firefox if I hold down the back button I get essentially  
breadcrumbs of page titles, so you could consider dropping them from  
the page itself to enable you to have a canonical URI for each concept.

But breadcrumbs can be nice too, and if you don't want to drop them,  
another thing you could do since you probably only have a few  
variations of breadcrumbs is try to have a canonical URI and send a  
different ETag for each variation. I don't know that this would work,  
because you'd have to figure out what breadcrumbs to show on that  
canonical URI based on which URI they came from. I'm not sure how  
consistently browsers will indicate the URI from which they were  
redirected in the canonical URI request. And even if that does work  
well enough, you don't get as good caching because proxies can't do  
content negotiation for you. So the proxies would have to ask the  
server each time if the appropriate representation is one of the ones  
it has cached. If so, your server wouldn't have to send the data to  
the proxy. But that's the only real speedup, and it isn't as good  
caching as having different URIs for each.

Another thing you could do is only redirect to a canonical URI for  
selected search engine robots. Search engines warn you not to do  
this. You aren't supposed to do something different for a search  
engine robot than for non-search engine robots. But they are mainly  
concerned about you having a page about poker that when a search  
engine robot shows up, you switch to a page about the representative  
of your district. Canonicalizing URIs would help search engines  
provide better results. So in this approach you get good caching and  
good search results, but at the risk of getting penalized for  
breaking the search engine's guidelines by being removed entirely  
from their index.

Or, you could just not have canonical URIs for each concept and  
accept the likelihood of reduced traffic from search engines. I  
wouldn't do that in my situation, but all design decisions depend on  
context. Maybe in your case being found via search engines isn't as  
important as being super cache-friendly and having breadcrumbs. You  
have to decide what tradeoffs to make, and it isn't easy. I have  
struggled a lot with balancing these things due to variation on pages  
coming from customization based on whether a user is logged in or  
not, and if so, who they are. One of the rules of thumb is to  
minimize variation as much as possible, and that's one reason I never  
show breadcrumbs on pages.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Mon, 2007-01-08 at 18:36 -0800, Roy T. Fielding wrote:
> On Jan 8, 2007, at 3:58 AM, Benjamin Carlyle wrote:
> > I see identity as the rock of vocabulary that allows unambigous
> > conversations to be had about what resources are and how we should
> > interact with them. You can then move on to definitions of resources
> > that help express the meaning of the classic HTTP methods:
> ...
> > This set of definitions defines the resource concept in a different  
> > way
> > to REST, and I think forms a subset of theoretical REST that can form
> > the basis of discussion about which methods a particular architecture
> > should have. It lies somewhere between the real web and REST theory  
> > as a
> > practical bridge of good web style.
...
> The problem with your model is that it doesn't respect reality.
> By axiomatizing away the notion of resource equivalence you simplify
> the model, but then your model is incapable of explaining the
> information theoretic properties of the Web that I just finished
> describing.  In your model, URI aliases are not an issue because
> they don't exist.  In the REST model, URI aliases are an issue
> because they reduce the perceived importance of a given resource
> and reduce the efficiency of caching resource representations.

Perhaps I have miscommunicated. Leaving aside the definition of
resources for the moment, what I have said is that at time t in good
REST style a url demarcates/selects state as well as defining a
potentially bidirectonal mapping between representations of various
types and its state. That state can overlap with the state of other
resources. I think that when the state overlap is perfect (and perhaps
the mapping is perfect also) this is what you mean by a URI alias.
However this hides a more general problem of overlapping state.

We have overlap when a blog front page shows ten articles, each of which
are accessible as a permantent link. Rather than duplicating content, it
would be more scalable to employ a technology such as HInclude[1] to
construct this page on the client side as required. Each individual page
can benefit from caching, and the template that sews them together would
be smaller. This is a related problem to that of a true alias, and I
suggest one that is is clearer when we talk about urls that demarcate
related state than when we talk about whether urls refer to the same
resource.

> So, the question then isn't how you might define resources.  The
> question is what do you intend to accomplish by doing so?  There
> are many ways to look at any given system, particularly when
> focusing on only one of the components.  An abstraction like REST
> is supposed to help the designer identify mismatches in the
> architecture.  Perhaps you don't see the problem because you
> aren't applying your model to the Web as a whole, but rather
> something more limited (such as a server-side development
> framework)?

The purpose of defining a resource to be a particular thing depends on
what you will use that definition for. I don't think the "resource is a
url is a resource" definition is simply meaningful at the server side.
The server has concepts of resource equivalence for its purposes, just
like anyone else in the architecture. If the server serves the same
representations for two urls it may think of them as the same resource.
However a proxy in the middle or a web browser isn't afforded the same
luxury. I think that at the machine level the resource and url concepts
can't be separated. Any particular point in the architecture may place
particular urls into equivalence classes, but those classes will be
different throughout the architecuture. At the machine level we can only
talk about the 1:1 url<->resource mapping.

If we talk about resources being the same a the human level we can work
with some latitude. However, the view is still a context-sensitive one.
Whether two urls refer to the same resource or not may depend on
language, regional, or other considerations. Apart from the
scheme-specific equivalence, reordering of query parmeters or matrix url
parameters, the very fact that multiple URLs are provided for a resource
is usually an indiciation that the identifications are not equivalent.

My interest in defining a resource is from a couple of perspectives:
* REST enthusiasts consistently get an inconsistent picture of what a
resource is. A central concept of an architectural style should be
conceptually simple and consistent, but we get into arguments about
whether resources are the same when we haven't clarified the "from which
perspective" question. url as identity is an impartial way of talking
about this concept.
* REST is not only GET. The dissertation talks about a resource as a
mapping to a set of values. This is fine for GET but doesn't provide a
framework under which we can assess the value of other methods. If
instead of talking about a resource as "what you see" we can talk about
a resource is "demarcating state and mapping to representationt types,
defining what you see and what it understands" we can then talk about
what a PUT might do. At time t we expect that a PUT will operate on the
same state that a GET would retrieve. Without including the definition
of the demarcated state as part of the resource we don't really have the
grounding to talk about PUT or other mutation methods.

So when people start arguing about whether two resources are the same or
not I am prone to step in and say that no two resources are the same,
though they may demarcate the same state. We can then talk generally
about resources that have overlapping state and what we should do about
them. From this grounding I can also say that PUT replaces this state,
POST adds to it, and DELETE PUTs the null state... but that business
logic may step in to leave things in states we don't expect, or change
state we didn't anticipate.

On Mon, 2007-01-08 at 09:45 -0500, Walden Mathews wrote: 
> Let's say you have a static page you intend to host forever, and
> you have one and only one representation you send for that page.
> You don't honor POST, PUT or DELETE (or any other unsafe
> method that may appear someday).  But, for reasons we don't
> care about right now, you support two URL's for that page:
> http://benjamin.com/thepage and http://benjamin.com/page1
> Clearly you have two identifiers here.  But are you willing to
> allow that they simply identify the same resource, and so there are
> not two resources, just one?  If not, why?

Maybe I'll run out of money someday or die, and someone else will take
over the domain. No machine in the architecture can infer that these are
different resources to themselves any more than a machine in the
architecture can infer that these are the same resource. All of the old
hyperlinks will be intact... but the server may now treat them
differently. Maybe they are two different files in the filesystem and
one becomes corrupt but the other doesn't. How sure do you need to be
that for all time they return the same values to call them the same?

On Mon, 2007-01-08 at 12:36 +0000, Jon Hanna wrote: 
> Benjamin Carlyle wrote:
> > I see this suggestion as a practical breakdown of the system. No node in
> > the system can sustainably claim equivalence of two urls except as
> > defined by scheme without adding "for my purposes".
> Sure it can.
> Just like I can say that the identifiers "Norma Jean Mortenson" and 
> "Marilyn Monroe" identify the same person.

... for the purposes of identifying a natural individual.

Now, for the purposes of talking about the movie actress vs her private
life we might have to rethink things. We can talk about Marilyn Monroe
outliving Norma Jean. Are they still the same resource? The very fact
that we constructed two identifiers suggests that the two will not
always be equivalent, certainaly not for all purposes. So same,
different? It depends on the purpose or intent of the entity who makes
the claim of equivalence. Should the identification of which resources
are the same depend on subjective perspectives? I would rather not for
such a central concept to the architectural style... but that is a
personal perspective.

Benjamin
[1] http://www.mnot.net/javascript/hinclude/

Hi Robert,

On Jan 9, 2007, at 11:42 PM, Robert Sayre wrote:

> On 1/10/07, Bill Venners <bv-svp@...> wrote:
>>
>> What do you mean by "in theory structured path segments allow more
>> versatile delegation of authority?"
>
> URIs are hierarchical. The "/" character is a delimiter. For example,
> examine which URLs automatically receive HTTP Basic auth credentials
> after an initial 401 response from
>
> http://example.com/foo/bar/baz
>
> vs.
>
> http://example.com/foo/bar;baz
>
Yes that's true.

>> Also, I personally am not sure whether semicolon separated params
>> would be prettier or uglier than traditional query params.
>
> Pretty paths are mapped to ugly query parameters, so there is no need
> to dwell on the relative merits. To use the first example from
> http://routes.groovie.org/manual.html#route-path
>
> http://example.com/myapp/feeds/electronics/atom.xml
>
> maps to
>
> http://example.com/myapp? 
> controller=feeds&category=electronics&action=atom&type=xml
>
> Of course, that is just one concrete example. It turns out that the
> commonly used parts of URI syntax are flexible enough to accommodate a
> rule-based mini language for routing. The rest of it hasn't been
> necessary yet, aside from implementation-specific uses. So, who cares
> if Tomcat breaks the semicolon? You can always use something less
> broken.
>
Perhaps I misunderstood you. I agree with your aesthetic sense that  
paths are prettier than queries in URIs. But I think that both path  
and queries are needed, so sometimes you will have query parts. The  
question I was asking is which form of embedding query params in URIs  
might they be the most pretty and user friendly?

http://www.artima.com/articles?o=a&t=java&p=7

Is the traditional way. But:

http://www.artima.com/articles;a,tjava,p7

or

http://www.artima.com/articles~a,tjava,p7

Could also be used in our architecture. I'm not sure that they are  
much prettier than the traditional query form, but the latter forms  
are shorter.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On 1/11/07, Jon Hanna <jon@...> wrote:
>  If I'm at http://www.examplenet/a/b/c and go to
>  http://www.examplenet/a/b/ and receive a 403 or anything else I don't
>  assume the application is buggy.

Why exactly is that "the way it's supposed to be"? One of the key
points to the web is that it is so explorable, and by exploring, the
user *will* make judgement upon the URL he/she tries out. I always
gets a bit annoyed at your scenario above; it means someone has missed
opportunities and broken the usability of the web. *Technically*
nothing is buggy or broken, but I still regard it as broken or buggy
by *design*.


Alexander
-- 
  Project Wrangler, Information Alchymist, UX, RESTafarian, Topic Maps
 (job hunting at http://shelter.nu/blog/2006/11/need-unique-talent.html)

------------------------------------------ http://shelter.nu/blog/ -------

On 1/10/07, Mike Schinkel <mikeschinkel@...> wrote:

> I'm starting to come to the conclusion that the resources I think are the
> same are actually different. Yes, they may have mostly the same content but
> they have different breadcrumbs which mean one can't be cached and served
> for the other.

Just because you navigated to a location circuitously doesn't mean
you'd want to see that path reflected in your breadcrumbs. You
probably want canonicalized breadcrumbs. You have a back button if you
want to retrace your steps; you have breadcrumbs to navigate the site.

Hugh

: I'm starting to come to the conclusion that the resources I think are the
: same are actually different. Yes, they may have mostly the same content 
but
: they have different breadcrumbs which mean one can't be cached and served
: for the other. Of course someone might argue that because the content on 
the
: different pages is so similar I should not create different resources; I
: should only have one. But I think that would be being pedantic in trying 
to
: optimize the caching benefit in exchange to the detriment of usability.

Separation Of Concerns suggests that your sites (and your life) will
be simpler if you decouple the thing you are seeking from the conversation
you had along the way.  That's not being pedantic either.

Walden 

: 
: Is it possible that we have an ingrained view of URI Opacity that is
: struggling with its evolvotion towards a more realistic and open-minded
: stance?
: 

Anything's possible, but in my experience it's the opposite: the location
bar is almost irrelevant, and becoming more and more so.

When I want to share a resource with a colleague, I am more apt to
tell him the string I googled on, and then refer to the nth entry in the
list than I am to cite the URL.  That's if we're in speaking range.  Other
than that, I cut and paste URI into emails and IM messages.

And it's been a long long time since I used lipstick to write a URL on
a party napkin.

Maybe it's just me.

Walden

: A agree he should present the information architecture through  
: hypertext, but it need not be "instead." It can be in addition to  
: presenting it in the URI. Like it or not, both the hypertext and the  
: URI are part of the user interface of a web application.

Yes, but the constraints on "good hypertext" are not the same
as the constraints on "good URI".  So when the information architecture
changes, where are you?
: 
: > Benefits:
: >
: > 1. You train your user to use the system at full leverage.
: >
: What do you mean by "full leverage?"

Let the server tell you where it is meaningful to go. Click instead
of type.

: Yes, that's what I mean by canonical. A canonical form, to which  
: other URIs that may mean the same thing redirect to. 

Oh, well in my analysis, "canonical URI" and "canonical URI form"
are two radically different ideas.

Walden

Hi Walden,

On Jan 10, 2007, at 5:45 PM, Walden Mathews wrote:

> : A agree he should present the information architecture through
> : hypertext, but it need not be "instead." It can be in addition to
> : presenting it in the URI. Like it or not, both the hypertext and the
> : URI are part of the user interface of a web application.
>
> Yes, but the constraints on "good hypertext" are not the same
> as the constraints on "good URI".  So when the information  
> architecture
> changes, where are you?

You're right, there it is much more cumbersome to change the URI than  
the representation, because people and software may have linked to,  
bookmarked, indexed, etc., that page at that URI. That's one reason  
it is so important to think hard about what your URIs should be in  
the first place. But you *can* change them and then redirect the old  
URIs to the new one.

For example, to log into Artima, originally I used a JSP that came  
with Jive software, and the URL was:

http://www.artima.com/login.jsp

I stopped using JSP at one point and switched to simply indicating  
what came back was HTML with a .html extension:

http://www.artima.com/login.html

Then I decided the name of the page should match the link to it,  
which was "sign in" not "log in," so I changed it to:

http://www.artima.com/signin.html

Then I read something, maybe "Cool URIs Don't Change," that convinced  
me that I shouldn't put the .html on the end. I also read something  
about search engines that indicated that words separated by  
underscores would be indexed. So I changed it to:

http://www.artima.com/sign_in

All the old forms redirect to the latest one. No broken links. No  
lost Google juice. Changing URIs can be done, it's just not as easy  
or advisable as changing representations.

> :
> : > Benefits:
> : >
> : > 1. You train your user to use the system at full leverage.
> : >
> : What do you mean by "full leverage?"
>
> Let the server tell you where it is meaningful to go. Click instead
> of type.
>
It isn't just users typing into the address bar, but users simply  
looking at the URI to get an idea of where they are in the info  
architecture. Yes, you can be successful with ugly URIs. Amazon has  
certainly trained their users to not try and figure out where they  
are based on the URI. But I still think short, crisp, meaningful URIs  
make a web app more user-friendly.

> : Yes, that's what I mean by canonical. A canonical form, to which
> : other URIs that may mean the same thing redirect to.
>
> Oh, well in my analysis, "canonical URI" and "canonical URI form"
> are two radically different ideas.
>
I'm curious how you define these two differently?

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Walden Mathews wrote:
> : I'm starting to come to the conclusion that the resources I 
> : think are the same are actually different. Yes, they may 
> : have mostly the same content but they have different 
> : breadcrumbs which mean one can't be cached and served
> : for the other. Of course someone might argue that because 
> : the content on the different pages is so similar I should not 
> : create different resources; I should only have one. But I 
> : think that would be being pedantic in trying to optimize 
> : the caching benefit in exchange to the detriment of usability.
> 
> Separation Of Concerns suggests that your sites (and your 
> life) will be simpler if you decouple the thing you are 
> seeking from the conversation you had along the way.  That's 
> not being pedantic either.

I understand what you are saying, but I believe your point about separation
of concerns does not hold for the use case we are discussing.  If we were
only discussing the path to get there it would be one thing, but we are
instead discussing the state of the resource which includes breadcrumbs.
Just like the probability of get heads on a coin flip does not change no
matter how many times you flip the coin, when someone is at the resource
with the specific breadcrumbs the may want to move up and then back down the
heirarchy and that has nothing to with with where they've been.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Walden Mathews wrote:
> : Is it possible that we have an ingrained view of URI Opacity that is
> : struggling with its evolvotion towards a more realistic and 
> : open-minded stance?
> Anything's possible, but in my experience it's the opposite: 
> the location bar is almost irrelevant, and becoming more and more so.

Well that is a statement without a shred of supporting evidence.  My
supporting evidence is a little stronger [1] [2].  I'm more than open to
considering other perspectives, but counter opinions without any supporting
evidence seem so troll-like its hard to take them as anything else.

> When I want to share a resource with a colleague, I am more 
> apt to tell him the string I googled on, and then refer to 
> the nth entry in the list than I am to cite the URL.  

Hmm. I'd rather give a colleague an exact identifier than a vague notion.
After all, I thought that was the whole point of URLs. Similary, when I have
friends over who don't know where I live, I give them my exact address
rather they tell them to go to "midtown atlanta and drive around looking for
a condo"...

I have an idea, maybe we should suggest to TimBL that he change RDF to just
require a link to a Google search rather than requiring all those peskly
little URIs; it would resolve so many pedantic little nuance debates.
Whadaya think, he'll go for it?

> if we're in speaking range.  Other than that, I cut and paste 
> URI into emails and IM messages.

Let's hope they are not too important, because if they are long they'll
break and your recipient might not be able to find them (just as I recently
couldn't find [3] because email ate the link).  But then I was forgetting
that you are not "in sales," I guess it's unimportant for you to communicate
such things reliably?

> And it's been a long long time since I used lipstick to write 
> a URL on a party napkin.

That's a rather strange writing utensil for a male, wouldn't you say?  Maybe
your choice of lipstick for writing is what is retarding your use of the
hand written word?

> Maybe it's just me.

I'm pretty sure it is.  Actually, it seems your main goal is to be contrary;
I dunno. Maybe that's just you.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

P.S. I probably shouldn't reply to emails that seem designed to bait me when
I'm really tired, but sometimes I do...

[1] http://www.useit.com/alertbox/990321.html
[2] http://www.w3.org/2001/tag/doc/metaDataInURI-31#guessing
[3]
http://www.pacificspirit.com/blog/2005/03/01/wsrest_continued_do_we_need_an_
http_transfer_soap_binding_and_simplified_wsdl

Bill Venners wrote:
> That's a good point. Caching is valuable too from a usability 
> perspective and a business one, because it will make the site 
> seem faster to users. I can think of a few options in that case.
> 
> One is to let go of the breadcrumbs. Users can use the back 
> button to back up. On Firefox if I hold down the back button 
> I get essentially breadcrumbs of page titles, so you could 
> consider dropping them from the page itself to enable you to 
> have a canonical URI for each concept.
> 
> But breadcrumbs can be nice too, and if you don't want to 
> drop them, another thing you could do since you probably only 
> have a few variations of breadcrumbs is try to have a 
> canonical URI and send a different ETag for each variation. I 
> don't know that this would work, because you'd have to figure 
> out what breadcrumbs to show on that canonical URI based on 
> which URI they came from. I'm not sure how consistently 
> browsers will indicate the URI from which they were 
> redirected in the canonical URI request. And even if that 
> does work well enough, you don't get as good caching because 
> proxies can't do content negotiation for you. So the proxies 
> would have to ask the server each time if the appropriate 
> representation is one of the ones it has cached. If so, your 
> server wouldn't have to send the data to the proxy. But 
> that's the only real speedup, and it isn't as good caching as 
> having different URIs for each.
> 
> Another thing you could do is only redirect to a canonical 
> URI for selected search engine robots. Search engines warn 
> you not to do this. You aren't supposed to do something 
> different for a search engine robot than for non-search 
> engine robots. But they are mainly concerned about you having 
> a page about poker that when a search engine robot shows up, 
> you switch to a page about the representative of your 
> district. Canonicalizing URIs would help search engines 
> provide better results. So in this approach you get good 
> caching and good search results, but at the risk of getting 
> penalized for breaking the search engine's guidelines by 
> being removed entirely from their index.
> 
> Or, you could just not have canonical URIs for each concept 
> and accept the likelihood of reduced traffic from search 
> engines. I wouldn't do that in my situation, but all design 
> decisions depend on context. Maybe in your case being found 
> via search engines isn't as important as being super 
> cache-friendly and having breadcrumbs. You have to decide 
> what tradeoffs to make, and it isn't easy. I have struggled a 
> lot with balancing these things due to variation on pages 
> coming from customization based on whether a user is logged 
> in or not, and if so, who they are. One of the rules of thumb 
> is to minimize variation as much as possible, and that's one 
> reason I never show breadcrumbs on pages.

Fair points all.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

Hugh Winkler wrote:
> > I'm starting to come to the conclusion that the resources I 
> think are 
> > the same are actually different. Yes, they may have mostly the same 
> > content but they have different breadcrumbs which mean one can't be 
> > cached and served for the other.
> 
> Just because you navigated to a location circuitously doesn't 
> mean you'd want to see that path reflected in your 
> breadcrumbs. You probably want canonicalized breadcrumbs. You 
> have a back button if you want to retrace your steps; you 
> have breadcrumbs to navigate the site.

To paraphrase Dan Connolly, I think you and I are on different planets.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to make the web more usable..."

> > Sure - if you want to dynamically define and re-define the 
> > implementation of the 'start' action, like upload some script. (I 
> > built a system like that once, it was very cool.) But I think this 
> > model is headed towards a queue, where you add work (pointers to 
> > entities) to be done.
> 
> yes. naturally, i would do it by sending a 
> '<start>http://example.org/openQRM/service/abc123</start>'  
> data to the http://example.org/openQRM/actions resource (a 
> queue of actions), or 
> http://example.org/openQRM/service/abc123/actions. but this 
> then seems very RPC
It's not really RPC since the method is 'add to resource' or 'extend
resource' and not a custom method.
It does border on a message oriented approach that quickly loses the clarity
of defined methods - a generic 'process this' for everything (which I don't
like, but that's just me).

 

> S. Mike Dierken wrote:
> >> now, it is hard for me to see 'start' and 'stop' as values of the 
> >> 'currentactivity' property. if anything, it looks like a 
> masquerade 
> >> of the RPC equivalent of posting to the VirtualEnvironment entity 
> >> with the pair 'action=start'.
> > What happens if a client sends 'start' twice? In a state transition 
> > diagram, that would be fairly easy to describe the desired 
> behavior. 
> > In an 'action
> 
> can you please elaborate? 
> 
> > oriented' approach, you'd have to special case that to prevent 
> > multiple initializations/etc.

Sorry I wasn't clear.
I pictured an implementation of 'start' that blindly allocated resources,
started processes, etc. 
If a 'start' message were sent twice, I wouldn't be surprised if this
resource allocation and process startup code tried to run a second time.
Although it would be easy to guard against this, if the meaning of the API
was "execute that code", it seems odd that the server would refuse to do
what it advertised as it's job.
With a state transfer, setting the state of a resource to the same value
twice is easy to describe and easy to accept multiple redundant messages and
honor the externally visible interface.

S. Mike Dierken wrote:
>  
> 
>> S. Mike Dierken wrote:
>>>> now, it is hard for me to see 'start' and 'stop' as values of the 
>>>> 'currentactivity' property. if anything, it looks like a 
>> masquerade 
>>>> of the RPC equivalent of posting to the VirtualEnvironment entity 
>>>> with the pair 'action=start'.
>>> What happens if a client sends 'start' twice? In a state transition 
>>> diagram, that would be fairly easy to describe the desired 
>> behavior. 
>>> In an 'action
>> can you please elaborate? 
>>
>>> oriented' approach, you'd have to special case that to prevent 
>>> multiple initializations/etc.
> 
> Sorry I wasn't clear.
> I pictured an implementation of 'start' that blindly allocated resources,
> started processes, etc. 
> If a 'start' message were sent twice, I wouldn't be surprised if this
> resource allocation and process startup code tried to run a second time.
> Although it would be easy to guard against this, if the meaning of the API
> was "execute that code", it seems odd that the server would refuse to do
> what it advertised as it's job.
> With a state transfer, setting the state of a resource to the same value
> twice is easy to describe and easy to accept multiple redundant messages and
> honor the externally visible interface.

excellent point.

how about something slightly different: the service resource can have a 'start schedule' property. then, the client can set this property to a date, or 'now'. when the service is started, this property becomes read-only until the service is stopped (by having a stop schedule property). the status of the service is a read only property, updated by the server.

> 
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

> 
> how about something slightly different: the service resource 
> can have a 'start schedule' property. then, the client can 
> set this property to a date, or 'now'. when the service is 
> started, this property becomes read-only until the service is 
> stopped (by having a stop schedule property). the status of 
> the service is a read only property, updated by the server.
Sounds reasonable. I'm interested to hear with others have to say though.

Re-reading the thread subject, and no disrespect intended.

On 10/01/07, Benjamin Carlyle <benjamincarlyle@...> wrote:

>  * REST is not only GET. The dissertation talks about a resource as a
>  mapping to a set of values. This is fine for GET but doesn't provide a
>  framework under which we can assess the value of other methods. If
>  instead of talking about a resource as "what you see" we can talk about
>  a resource is "demarcating state and mapping to representationt types,
>  defining what you see and what it understands" we can then talk about
>  what a PUT might do.

IMHO this simply isn't 'REST for the rest of us'
It's back in thesis land, abstracted to hell and gone.

If this is good/valuable, please find some plain English to say it.

regards



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Hello,

On 10/01/07, Bill Venners <bv-svp@...> wrote:
> On Jan 10, 2007, at 6:27 AM, Mike Schinkel wrote:
> > I'm starting to come to the conclusion that the resources I think
> > are the
> > same are actually different. Yes, they may have mostly the same
> > content but
> > they have different breadcrumbs which mean one can't be cached and
> > served
> > for the other. Of course someone might argue that because the
> > content on the
> > different pages is so similar I should not create different
> > resources; I
> > should only have one. But I think that would be being pedantic in
> > trying to
> > optimize the caching benefit in exchange to the detriment of
> > usability.
> >
> That's a good point. Caching is valuable too from a usability
> perspective and a business one, because it will make the site seem
> faster to users. I can think of a few options in that case.
>
> One is to let go of the breadcrumbs. Users can use the back button to
> back up. On Firefox if I hold down the back button I get essentially
> breadcrumbs of page titles, so you could consider dropping them from
> the page itself to enable you to have a canonical URI for each concept.

You may also keep one URI for a page, display one set of possible
breadcrumbs in that page representation, and for any other path the
user takes, just replace the breadcrumbs in the DOM via javascript.

You keep the cache happy, you keep the bots happy, and the users can
get different breadcrumbs via a separate js file refered in the page,
that somehow tracks their path.

The only thing that shouldn't be cacheable is that js URL (if you
generate it over each request), which is anyway significant smaller
that the whole page.

Cheers,
-- 
Laurian Gridinoc, purl.org/net/laur

Alexander Johannesen wrote:
> On 1/11/07, Jon Hanna <jon@...> wrote:
>>  If I'm at http://www.examplenet/a/b/c and go to
>>  http://www.examplenet/a/b/ and receive a 403 or anything else I don't
>>  assume the application is buggy.
> 
> Why exactly is that "the way it's supposed to be"?

Nothing beyond the documented constraints is the way it's supposed to 
be. This isn't, the scenario where it doesn't give a 403 isn't either.

> One of the key
> points to the web is that it is so explorable, and by exploring, the
> user *will* make judgement upon the URL he/she tries out. I always
> gets a bit annoyed at your scenario above; it means someone has missed
> opportunities and broken the usability of the web. *Technically*
> nothing is buggy or broken, but I still regard it as broken or buggy
> by *design*.


That assumes not only that implementation factors made that feasible, or 
didn't just make it too hard to work nicely, but that 
http://www.examplenet/a/b/ could be reasonably represented AND that that 
representation is one you would want the user to see (not always the 
case by a long shot).

I do like it when http://www.examplenet/a/b/ works. I do try to make 
http://www.examplenet/a/b/ work when applicable, but it's not always 
going to.

This is on top of the fact that such structuring of URIs meets a 
different set of criteria to others that have to be met to work well 
with the web. Using both is the ideal, but arguing that it's a matter of 
one versus the other is bogus.

Mike Schinkel wrote:
> Hugh Winkler wrote:
>> Just because you navigated to a location circuitously doesn't 
>> mean you'd want to see that path reflected in your 
>> breadcrumbs. You probably want canonicalized breadcrumbs. You 
>> have a back button if you want to retrace your steps; you 
>> have breadcrumbs to navigate the site.
> 
> To paraphrase Dan Connolly, I think you and I are on different planets.


My browser has a back button, so I'd rather use the "bread crumbs" from 
his planet than yours.

On Thu, 2007-01-11 at 08:18 +0000, Dave Pawson wrote:
> Re-reading the thread subject, and no disrespect intended.
> On 10/01/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > * REST is not only GET. The dissertation talks about a resource as a
> > mapping to a set of values. This is fine for GET but doesn't provide
> a
> > framework under which we can assess the value of other methods. If
> > instead of talking about a resource as "what you see" we can talk
> about
> > a resource is "demarcating state and mapping to representationt
> types,
> > defining what you see and what it understands" we can then talk
> about
> > what a PUT might do.
> IMHO this simply isn't 'REST for the rest of us'
> It's back in thesis land, abstracted to hell and gone.
> If this is good/valuable, please find some plain English to say it.

Point taken. In plain english:

A resource isn't just the representations/documents it returns when you
do a GET. The resource means something. It is the service exposing its
interface as information rather than methods. A GET takes a copy of the
information in a particular document format for consumption by the user.
A PUT replaces that information with information provided by the user.
POST adds information to the resource, and DELETE PUTs the null state.
These methods can enable interaction with any kind of information. REST
allows other methods to be defined, but they always act on generic
information.

Consider the java bean concept. A client has an expectation that
get_foo() and set_foo() are operating on the same thing. The thing might
be a simple member variable, but might just as easily be a more abstract
concept. Either way, the fact that we have a uniform way of accessing
the information makes it possible to develop applications we otherwise
couldn't. We can do property-based editing with a java-bean. If we used
arbitrary methods we couldn't. Standard content types are also required.

Sometimes when we modify a resource, it will only be that resource that
changes. However, just as often the change will set other processing in
motion. When we POST a new purchase order we expect resources that
describe the set of open purchase orders to change. This information is
accessible from multiple resources, and could conceivably be modified
usring one of several resources. We can talk about resource that share
information as overlapping. Changes that might not be a simple overlap
may include a commission being paid for the puchase order achieving a
particular state of completion. Any kind of business logic may be
performed by the server so long as it provides a reasonable
interpretation of the request to modify a particular resource. Even a
GET is likely to have sort of side-effect. A log file is bound to be
updated, at least.

Benjamin.

Mike Schinkel wrote:
> 
> 
> Hugh Winkler wrote:
>  > > I'm starting to come to the conclusion that the resources I
>  > think are
>  > > the same are actually different. Yes, they may have mostly the same
>  > > content but they have different breadcrumbs which mean one can't be
>  > > cached and served for the other.
>  >
>  > Just because you navigated to a location circuitously doesn't
>  > mean you'd want to see that path reflected in your
>  > breadcrumbs. You probably want canonicalized breadcrumbs. You
>  > have a back button if you want to retrace your steps; you
>  > have breadcrumbs to navigate the site.
> 
> To paraphrase Dan Connolly, I think you and I are on different planets.

Actually, that's not unreasonable from a usability/accessibility 
perspective. There's no need to have your site walk reflected in the 
breadcrumb, and there is something to be said for 'static' breadcrumbs 
that indicate the site's IA. This is more important today, as many 
people are dropped straight into a site via a search engine.

cheers
Bill

--- In rest-discuss@yahoogroups.com, Benjamin Carlyle
<benjamincarlyle@...> wrote:
>

> ... When we POST a new purchase order we expect resources that
> describe the set of open purchase orders to change. This information is
> accessible from multiple resources, and could conceivably be modified
> usring one of several resources. We can talk about resource that share
> information as overlapping. Changes that might not be a simple overlap
> may include a commission being paid for the puchase order achieving a
> particular state of completion. Any kind of business logic may be
> performed by the server so long as it provides a reasonable
> interpretation of the request to modify a particular resource. Even a
> GET is likely to have sort of side-effect. A log file is bound to be
> updated, at least.
> 
> Benjamin.
>

So here's a question:
What about PUT? When you PUT something can other resources change? If
so are those changes also required to be idempotent? Does that mean
that a resource that is a counter for the number of times another
resource was PUT is "illegal"?

Also, I assume that side-effects of GET (as well as the non-idempotent
side-effects of PUT and DELETE) are only allowed as long as they are
not reflected in the resource space in any way? e.g. you should never
make the log part of your interface, accessible via GET. Correct?
(Note that I'm not implying that if for some reason you provided some
HTTP access to your log file for administrators that all is lost.
Arguably this is a different interface.)

For those interested, I posted the following on the WHATWG working group
blog proposing URI Templates be used for forms for WebForms 2.0 :

http://blog.whatwg.org/proposing-uri-templates-for-webforms-20

I posted a longer one here:

http://blog.welldesignedurls.org/2007/01/11/proposing-uri-templates-for-webf
orms-2/

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

On 1/10/07, Mike Schinkel <mikeschinkel@...> wrote:
> So by "parameter" do you mean attribute?

Doh, yes.

> For example, would this be
> workable where newer browsers would use "template" instead of "action?"

Yup.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Laurian Gridinoc wrote:
> You may also keep one URI for a page, display one set of 
> possible breadcrumbs in that page representation, and for any 
> other path the user takes, just replace the breadcrumbs in 
> the DOM via javascript.
> 
> You keep the cache happy, you keep the bots happy, and the 
> users can get different breadcrumbs via a separate js file 
> refered in the page, that somehow tracks their path.
> 
> The only thing that shouldn't be cacheable is that js URL (if 
> you generate it over each request), which is anyway 
> significant smaller that the whole page.

Thanks. Since writing this I had thought of that as providing a better
solution, but still not best. I believe that URL is part of the user
interface so it doesn't address that part of the concern, unfortunately.
But, I'll continue to research.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

Jon Hanna wrote:
> Mike Schinkel wrote:
> > Hugh Winkler wrote:
> >> Just because you navigated to a location circuitously doesn't mean 
> >> you'd want to see that path reflected in your breadcrumbs. You 
> >> probably want canonicalized breadcrumbs. You have a back button if 
> >> you want to retrace your steps; you have breadcrumbs to 
> >> navigate the site.
> > To paraphrase Dan Connolly, I think you and I are on 
> different planets.
> My browser has a back button, so I'd rather use the "bread 
> crumbs" from his planet than yours.

And I'm happy for you to do so. The different, however, is I'm not trying to
keep you or Hugh from doing it your ways.

Bill de hOra wrote:
> Actually, that's not unreasonable from a 
> usability/accessibility perspective. There's no need to have 
> your site walk reflected in the breadcrumb,

I respectfully state that that is a matter of opinion. Like Jakob Neilsen, I
believe that URL is UI[1] and if the URL doesn't reflect the site structure
then they are not "hackable" in the same way and hence not as good of UI.
Everyone tends to optimize for those things they value, and I think you and
a few others here don't really value some things that are important to me,
and vice versa. The problem comes when authoritative findings dictate one
set of values at the expense of others instead of finding a way to service
everyone's values.

> there is something to be said for 'static' breadcrumbs 
> that indicate the site's IA. This is more important today, 
> as many people are dropped straight into a site via a 
> search engine.

Site's IA? 

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

[1] http://www.useit.com/alertbox/990321.html

Mike Schinkel wrote:

> Bill de hOra wrote:
>  > Actually, that's not unreasonable from a
>  > usability/accessibility perspective. There's no need to have
>  > your site walk reflected in the breadcrumb,
> 
> I respectfully state that that is a matter of opinion. Like Jakob Neilsen, I
> believe that URL is UI[1] and if the URL doesn't reflect the site structure
> then they are not "hackable" in the same way and hence not as good of UI.

I don't disagree with either of those statements, but I don't understand 
  what your point is either. Countering what I think about good UI 
design  for breadcrumbs with what you think is good UI design for URLs 
doesn't make sense (to me) since breadcrumbs aren't URIs and don't 
necessarily depend on the URIs construction.

Anyway, the point I'm trying to make is this - there's no reason to 
dynamically generate the breadcrumb trail based on on the user's walk 
through the site. The follow on point is that URL design need have 
nothing to do with page breadcrumbs. Finally, as an aside, it's easier 
to arrange caching for pages with 'static' breadcrumbs. Everybody wins.


>  > there is something to be said for 'static' breadcrumbs
>  > that indicate the site's IA. This is more important today,
>  > as many people are dropped straight into a site via a
>  > search engine.
> 
> Site's IA?

Information Architecture.

cheers
Bill

Mike Schinkel wrote:
> I respectfully state that that is a matter of opinion. Like Jakob Neilsen, I

A funny person to cite. Doesn't he complain about breadcrumbs that 
aren't showing a way into a hierarchical structure? Still, it's his 
fault, since apparently he gave them that name, and the name does imply 
that it's showing a path that was taken.

> believe that URL is UI[1] and if the URL doesn't reflect the site structure
> then they are not "hackable" in the same way and hence not as good of UI.

This doesn't mean they have to be broken.

It's actually easier to do both at the same time, IME.

Hi Laurian,

On Jan 11, 2007, at 2:18 AM, Laurian Gridinoc wrote:

> You may also keep one URI for a page, display one set of possible
> breadcrumbs in that page representation, and for any other path the
> user takes, just replace the breadcrumbs in the DOM via javascript.
>
> You keep the cache happy, you keep the bots happy, and the users can
> get different breadcrumbs via a separate js file refered in the page,
> that somehow tracks their path.
>
> The only thing that shouldn't be cacheable is that js URL (if you
> generate it over each request), which is anyway significant smaller
> that the whole page.
>
I'm not sure this would work. I tried figuring out how to do give  
users customized versions of pages using JavaScript, as that approach  
was suggested to me by some folks on this list. I don't want to do it  
that way for several reasons, but I also couldn't see how it would be  
possible. The trouble is: how does a page know which alternate  
JavaScript URL to grab if the page is always identical? If the page  
isn't identical, but only differs in that one URL, then you can't  
cache it at one URL without resorting to multiple entities. And if  
you're going to do that, you may as well just put the breadcrumbs on  
the page on the server and have each of those versions be entities.

One thing JS could do differently is look in the cookies, but am I  
wrong in assuming a cache intermediary would cache all the response  
headers too, and send them along (other than perhaps changing a few  
to indicate the response came from a cache.) If so, then you can't  
change the cookies either without resorting to multiple entities.  
Again, if you're going to do that, why not just have the server put  
the breadcrumbs in and call those multiple entities.

If you force them to log in and they get a session ID cookie, then  
that could be accessed by the JS. (But the breadcrumbed page itself  
wouldn't set that cookie in its response.) But then you just have one  
breadcrumb per user session per URI. And what if they have two  
browsers windows open. This has the same problem using session to  
hold state always has.

Am I missing some way to do this, or am I correct in concluding it  
isn't possible?

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

----- Original Message ----- 
From: "Bill Venners" <bv-svp@...>
To: "Walden Mathews" <waldenm@...>
Cc: "'REST Discuss'" <rest-discuss@yahoogroups.com>
Sent: Wednesday, January 10, 2007 9:20 PM
Subject: Re: [rest-discuss] Benefits of Canonical URLs (was Request for 
feedback: REST for the Rest of Us)


: Hi Walden,
:
: On Jan 10, 2007, at 5:45 PM, Walden Mathews wrote:
:
: > : A agree he should present the information architecture through
: > : hypertext, but it need not be "instead." It can be in addition to
: > : presenting it in the URI. Like it or not, both the hypertext and the
: > : URI are part of the user interface of a web application.
: >
: > Yes, but the constraints on "good hypertext" are not the same
: > as the constraints on "good URI".  So when the information
: > architecture
: > changes, where are you?
:
: You're right, there it is much more cumbersome to change the URI than
: the representation, because people and software may have linked to,
: bookmarked, indexed, etc., that page at that URI. That's one reason
: it is so important to think hard about what your URIs should be in
: the first place. But you *can* change them and then redirect the old
: URIs to the new one.
:
: For example, to log into Artima, originally I used a JSP that came
: with Jive software, and the URL was:
:
: http://www.artima.com/login.jsp
:
: I stopped using JSP at one point and switched to simply indicating
: what came back was HTML with a .html extension:
:
: http://www.artima.com/login.html
:
: Then I decided the name of the page should match the link to it,
: which was "sign in" not "log in," so I changed it to:
:
: http://www.artima.com/signin.html
:
: Then I read something, maybe "Cool URIs Don't Change," that convinced
: me that I shouldn't put the .html on the end. I also read something
: about search engines that indicated that words separated by
: underscores would be indexed. So I changed it to:
:
: http://www.artima.com/sign_in
:
: All the old forms redirect to the latest one. No broken links. No
: lost Google juice. Changing URIs can be done, it's just not as easy
: or advisable as changing representations.

Well, the above is a story of the kind of obsession I think
we ought not fall into.  It comes from valuing the wrong
things, IMO.  Sorry.

: It isn't just users typing into the address bar, but users simply
: looking at the URI to get an idea of where they are in the info
: architecture.

We're circling round and round.  "Where we are in the info
architecture" is not a primary concern.  A primary concern is
where to need to be next and how to get there.  Good hypertext
is the way.  But stick to tea leaves if you like.  I'm tired.


 Yes, you can be successful with ugly URIs. Amazon has
: certainly trained their users to not try and figure out where they
: are based on the URI. But I still think short, crisp, meaningful URIs
: make a web app more user-friendly.

Ugly or beautiful, they are just tokens in a system that is rich with
legitimate description, if you do it right.

: > Oh, well in my analysis, "canonical URI" and "canonical URI form"
: > are two radically different ideas.
: >
: I'm curious how you define these two differently?

I haven't seen these terms laid out anywhere.  So I'm just applying
the rules of English grammar.  The former simply says the one URI
is the preferred and all other equivalents are aliases.  The latter is
a matter of specifying the arrangement of meaningful fragments within
the URI string so it can be understood.

I think the first is good practice, while the second is marginally
useful, but tends to compete with better solutions.  To summarize.

Walden 

: I understand what you are saying, but I believe your point about 
separation
: of concerns does not hold for the use case we are discussing.  If we were
: only discussing the path to get there it would be one thing, but we are
: instead discussing the state of the resource which includes breadcrumbs.
: Just like the probability of get heads on a coin flip does not change no
: matter how many times you flip the coin, when someone is at the resource
: with the specific breadcrumbs the may want to move up and then back down 
the
: heirarchy and that has nothing to with with where they've been.

I doubt the resource includes breadcrumbs (whatever they are -- I thought
I knew but now I know I don't).  Perhaps some representations do.

If two representations of the same resource could differ in the breadcrumb
dept., and that's somehow not about navigation to that resource, then
could you please give a short example so I can know what you're talking
about?

Walden 

Did anybody mention this article in relation to this issue?
http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/

What do people think of it?

There's also a critique at:
http://www.addsimplicity.com/adding_simplicity_an_engi/2007/01/a_real_ebay_arc.html

One of his main counter-arguments seems to be CompleteSale, which I
thought Duncan Cragg could have handled more explicitly, as he did
with ResponseToBestOffer.

Hi Mike,

That would be so nice to see such a proposal accepted for HTML 5.0, in 
addition to adding support for PUT and DELETE actions.

Even though the URI template RFC is not finalized yet, we already have a 
complete support for it, on the server-side, in the Restlet framework. 
We happily use them for our URI-based routing and I think they add a lot 
of expressiveness while keeping a simple syntax. Usage example:
http://www.restlet.org/tutorial#part11

They are also supported in WADL, the RESTful description language, and 
in the OpenSearch specification. Extending their usage to HTML forms 
sounds like a logical and useful step.

Regards,
Jerome Louvel
http://blog.noelios.com


Mike Schinkel wrote :
> For those interested, I posted the following on the WHATWG working group
> blog proposing URI Templates be used for forms for WebForms 2.0 :
> 
> http://blog.whatwg.org/proposing-uri-templates-for-webforms-20
> 
> I posted a longer one here:
> 
> http://blog.welldesignedurls.org/2007/01/11/proposing-uri-templates-for-webf
> orms-2/

this article is what prompted me to submit this thread in the first place. if not, i would have probably gone the "ebay" way of defining actions in the url. i also read http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html in which the real architect continues the dialog from his point of view.

what i don't like about duncan's post is that he addresses only getter and setter business functions, not real ones, those that actually create a process. it is very easy to say that instead of getFoo, you can GET http://example.com/foo. it is harder when you want to model a doSomething function.

Bob Haugen wrote:
> 
> 
> Did anybody mention this article in relation to this issue?
> http://duncan- cragg.org/ blog/post/ business- functions- 
> rest-dialogues/ 
> <http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/>
> 
> What do people think of it?
> 
> There's also a critique at:
> http://www.addsimpl icity.com/ adding_simplicit y_an_engi/ 2007/01/a_ 
> real_ebay_ arc.html 
> <http://www.addsimplicity.com/adding_simplicity_an_engi/2007/01/a_real_ebay_arc.html>
> 
> One of his main counter-arguments seems to be CompleteSale, which I
> thought Duncan Cragg could have handled more explicitly, as he did
> with ResponseToBestOffer .
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

On Fri, 2007-01-12 at 15:23 +0200, Ittay Dror wrote:
> this article is what prompted me to submit this thread in the first
> place. if not, i would have probably gone the "ebay" way of defining
> actions in the url. i also read
> http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html in which the real architect continues the dialog from his point of view.
> 
> what i don't like about duncan's post is that he addresses only getter
> and setter business functions, not real ones, those that actually
> create a process. it is very easy to say that instead of getFoo, you
> can GET http://example.com/foo. it is harder when you want to model a
> doSomething function.

I think this is exactly the point, though. HTTP's REST replaces the
doSomething concept with a "make something so" concept. If you think
about it, all doSomething can be modelled this way. Instead of "make
this kind of state transition", just "make your state this". You have to
get into specific examples to see how this works. The first example of
starting or stopping a function is the same as setting a running
resource to false or true. Do you have more examples in mind? What kind
of process would you like to create?

The general approach to process creation would either be:
POST a representation of the process to a factory resource to create it.
PUT a representation of the process to the process resource to change
its operation.
DELETE the process to destroy it.
PUT a false to the process's "running" resource to suspend it.
etc ...

Benjamin.

On 12/01/07, Benjamin Carlyle <benjamincarlyle@...> wrote:


>  I think this is exactly the point, though. HTTP's REST replaces the
>  doSomething concept with a "make something so" concept. If you think
>  about it, all doSomething can be modelled this way. Instead of "make
>  this kind of state transition", just "make your state this". You have to
>  get into specific examples to see how this works. The first example of
>  starting or stopping a function is the same as setting a running
>  resource to false or true.


Great description for the 'rest for the rest of us'.

Thanks Benjamin.


regards


-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Benjamin Carlyle wrote:
> On Fri, 2007-01-12 at 15:23 +0200, Ittay Dror wrote:
>> this article is what prompted me to submit this thread in the first
>> place. if not, i would have probably gone the "ebay" way of defining
>> actions in the url. i also read
>> http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html in which the real architect continues the dialog from his point of view.
>>
>> what i don't like about duncan's post is that he addresses only getter
>> and setter business functions, not real ones, those that actually
>> create a process. it is very easy to say that instead of getFoo, you
>> can GET http://example.com/foo. it is harder when you want to model a
>> doSomething function.
> 
> I think this is exactly the point, though. HTTP's REST replaces the
> doSomething concept with a "make something so" concept. If you think
> about it, all doSomething can be modelled this way. Instead of "make
> this kind of state transition", just "make your state this". You have to
> get into specific examples to see how this works. The first example of
> starting or stopping a function is the same as setting a running
> resource to false or true. Do you have more examples in mind? What kind
> of process would you like to create?

what about passing parameters, like 'start at date'? or 'start at date with X resources'? the first can be modeled by setting 'date' to a 'schedule' property of the service. but how can the second? 

also, many suggestions, while very good in themselves mean that the rest API is no longer just a gateway to the system's functionality. it enforces the system to be built in a certain way (like creating 'process' resources that can be monitored and canceled). while rest is an excellent approach to API, systems are usually designed by object-oriented, procedural or functional approaches. 

what i would love to see is a separation of API and model, in the same sense as MVC. i want to construct my system with whatever approach is suitable for me and then be able to provide a restful API to it, without having it break my system model.

> 
> The general approach to process creation would either be:
> POST a representation of the process to a factory resource to create it.
> PUT a representation of the process to the process resource to change
> its operation.
> DELETE the process to destroy it.
> PUT a false to the process's "running" resource to suspend it.
> etc ...
> 
> Benjamin.
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

On Fri, 2007-01-12 at 17:05 +0200, Ittay Dror wrote:
> Benjamin Carlyle wrote:
> > On Fri, 2007-01-12 at 15:23 +0200, Ittay Dror wrote:
> >> what i don't like about duncan's post is that he addresses only
> getter
> >> and setter business functions, not real ones, those that actually
> >> create a process. it is very easy to say that instead of getFoo,
> you
> >> can GET http://example.com/foo. it is harder when you want to model
> a
> >> doSomething function.
> > I think this is exactly the point, though. HTTP's REST replaces the
> > doSomething concept with a "make something so" concept. If you think
> > about it, all doSomething can be modelled this way. Instead of "make
> > this kind of state transition", just "make your state this". You
> have to
> > get into specific examples to see how this works.
> what about passing parameters, like 'start at date'? or 'start at date
> with X resources'? the first can be modeled by setting 'date' to a
> 'schedule' property of the service. but how can the second? 

The "with X resources" sounds like it is part of your function
definition. In that case, it should be part of what you POST into your
schedule resource:

POST http://example.com/functionSchedule HTTP/1.1
Content-Type: application/calendar+xml

<vevent>
	<priority>5</priority>
	<dtstart>2007-01-13T08:55:00Z</dtstart>
	<dtend>2007-01-13T09:55:00Z</dtend>
	<content type="application/my-function-definition">
		<function>
			<resource>resource1</resource>
			<resource>resource2</resource>
			<resource>resource3</resource>
		</function>
	</content>
</vevent>

However, the exact design would no doubt rely on factors that are not
easy to communicate via email.

> also, many suggestions, while very good in themselves mean that the
> rest API is no longer just a gateway to the system's functionality. it
> enforces the system to be built in a certain way (like creating
> 'process' resources that can be monitored and canceled). while rest is
> an excellent approach to API, systems are usually designed by
> object-oriented, procedural or functional approaches. 

You won't be able to write a "REST Proxy" for your system that
automatically translates REST requests to internal method invocations.
The REST request and the internal method are based on different
conceptual models. You will either need to write glue code that maps
these conceptual models to each other, or push the REST approach further
back into your applications. In the glue code model the resources
introduced as part of the REST Proxy would be created and maintained
with the glue as handles to internal state. You would just have to be
careful about the API and internal state models becoming inconsistent.

I'm an advocate of pushing REST futher back myself, although this is
most effective when the system behind the curtain is a distributed
object environment that will benefit from the application of REST
principles.

> what i would love to see is a separation of API and model, in the same
> sense as MVC. i want to construct my system with whatever approach is
> suitable for me and then be able to provide a restful API to it,
> without having it break my system model.

So long as you are prepared to write the glue code, there is nothing to
stop this from happening. You can encapsulate the non-RESTful system in
a RESTful container. Just don't expect it to be a 1:1 mapping. If the
inside is not RESTful and the outside is RESTful, it will be n:m.

Benjamin.

Benjamin Carlyle wrote: 
> I'm an advocate of pushing REST futher back myself, although this is
> most effective when the system behind the curtain is a distributed
> object environment that will benefit from the application of REST
> principles.
> 
> > what i would love to see is a separation of API and model, in the same
> > sense as MVC. i want to construct my system with whatever approach is
> > suitable for me and then be able to provide a restful API to it,
> > without having it break my system model.
> 
> So long as you are prepared to write the glue code, there is nothing to
> stop this from happening. You can encapsulate the non-RESTful system in
> a RESTful container. Just don't expect it to be a 1:1 mapping. If the
> inside is not RESTful and the outside is RESTful, it will be n:m.
> 
> Benjamin.
>

This feels like over-engineering.  It's not because something can be
mapped to concept X that it should be.  Otherwise, why would we ever
have left the realm of Turing machines.

Having worked for many years in designing systems for developers, I
find it incredibly important to connect intuition to implementation. 
Mapping everything into POST-generic-stuff-here isn't useful for
humans, because it doesn't partition the space we need to reason in. 
Without partitions, we can't apply the conquer-and-divide reasoning
scheme (a.k.a. separation of concerns).

Modeling certain operations as RPC has its place, imho.  That's why I
defined the Behavior pattern in 'REST for the rest of us' [1]
(although, I'm thinking about renaming it to something less abstract).
 Like anything else, it should be used only when required, but when it
is required, it shouldn't be shunned.

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

[1]
http://doc.opengarden.org/index.php?title=Articles/REST_for_the_Rest_of_Us&bc=2

Don Box says that "For what it's worth, I happen to agree, as do many 
folks I talk to in the big house."

http://pluralsight.com/blogs/dbox/archive/2007/01/12/45674.aspx

Maybe we will see better REST support from Microsoft. Things I would 
like:
 - REST Framework for .NET (rather than having to code everything 
from the HTTP pipeline up).
 - REST Module for IIS (don't try to re-use the WebDAV module).
 - More guides, articles and case-studies covering RESTful 
architectures on MSDN.
 - Dedicated REST evangelists (just as there are some dedicated to WS-
*).
 - Acceptance of REST, as opposed to 'adopt and extend' (Don's hi-
REST / lo-REST article a while back gives me cause for concern here).
 - RESTful improvements to IE8 (quite a long list, starting with 
<form> support for PUT and DELETE, including a better Basic|Digest 
Authentication story, etc).
 - RDF / RDFS / SPARQL support in the .NET Framework (I am firmly of 
the opinion that REST works best when leveraging semantic 
technologies). I would be bowled over if N3 was also supported.
 - RelaxNG schema support (for the same reason as the previous point -
 XmlSchema / XPath are too brittle in the face of REST).
 - I guess that part of the community would like support for Atom
(Pub) as well, although I'm not personally that fussed.

What else would the group add to this list?

Regards, Alan Dean

Hello everyone. I'm normally a lurker but I have a quetion for the group.

Let me paint the scenario for you:

I have a Resource. If the User is anonymous, when they GET the
Resource, the Representation returned displays one set of information.
However, if the User if of the type Admin, the Representation returned
displays the same information, but with additional information
relevant to the Admin User.

My question is this: should the decision to display this different
response data rest with the Resource, or the Representation: that is,
should the Resource always return ALL the information, regardless of
the User type, and let the Representation determine this information
to be returned based on User type, or should the data the Resource
returns be limited based on User type? The latter would, in effect
create two Resources, whereas the first would call the same Resource,
and filter the response based on rules defined in the Representation.

I feel that the Resource should return all the information and that it
is the responsibility of the Representation to determine what is
displayed. What do you guys think?

Cheers!

Ben

On Sat, 2007-01-13 at 02:58 +0000, Steve G. Bjorg wrote:
> Benjamin Carlyle wrote: 
> > I'm an advocate of pushing REST futher back myself, although this is
> > most effective when the system behind the curtain is a distributed
> > object environment that will benefit from the application of REST
> > principles.
> > > what i would love to see is a separation of API and model, in the
> same
> > > sense as MVC. i want to construct my system with whatever approach
> is
> > > suitable for me and then be able to provide a restful API to it,
> > > without having it break my system model.
> > So long as you are prepared to write the glue code, there is nothing
> to
> > stop this from happening. You can encapsulate the non-RESTful system
> in
> > a RESTful container. Just don't expect it to be a 1:1 mapping. If
> the
> > inside is not RESTful and the outside is RESTful, it will be n:m.
> This feels like over-engineering. It's not because something can be
> mapped to concept X that it should be. Otherwise, why would we ever
> have left the realm of Turing machines.
...
> Modeling certain operations as RPC has its place, imho. That's why I
> defined the Behavior pattern in 'REST for the rest of us' [1]
> (although, I'm thinking about renaming it to something less abstract).
> Like anything else, it should be used only when required, but when it
> is required, it shouldn't be shunned.

I would be inclined to call this an antipattern. I think it should be
avoided. Mapping arbitrary method invocation into POST doesn't help web
browsers or other generic network components interact with the resource.
It is more of a back-door for when you don't really want to do REST for
whatever reason... and there may well be reasons. However, I would be
inclined to look to adding special request methods rather than hiding
them in the body of a POST request or in a url. If you are using RPC
instead of REST style, you might as well put your method where the
protocol says it should go.

Do you have any examples of this pattern being applied that do not
cleanly map into standard HTTP methods?

Benjamin.

On Sat, 2007-01-13 at 10:30 +0000, omarshariffdontlikeit wrote:
> I have a Resource. If the User is anonymous, when they GET the
> Resource, the Representation returned displays one set of information.
> However, if the User if of the type Admin, the Representation returned
> displays the same information, but with additional information
> relevant to the Admin User.

> My question is this: should the decision to display this different
> response data rest with the Resource, or the Representation: that is,
> should the Resource always return ALL the information, regardless of
> the User type, and let the Representation determine this information
> to be returned based on User type, or should the data the Resource
> returns be limited based on User type? The latter would, in effect
> create two Resources, whereas the first would call the same Resource,
> and filter the response based on rules defined in the Representation.

I would be inclined to say that these different return values are coming
about because what you really have are two different resources. Perhaps
a more specific statement of your use case would help clarify things.

I think when you talk about filtering or operations on the
representation you are referring to what happens within the program that
is maintaining the resource. If so, this is an internal matter. Only
what the user sees is important in the REST architecture. The design of
your program is a separate matter: Should you have two objects for the
two resources, or should you have one object and another that provides
filtering on the representation that object produces? Answer: It
depends :)

REST permits intermediataries to be introduced into an architecture, and
this layering doesn't stop at the edge of your process. The protocol
handling code is an intermediatary. You might have a pipeline that
contains authentication modules and other transformations.

In this case it would seem that security is an issue. If so, you would
want to look at whether tagging information as admin-only and filtering
it out is safer than constructing separate layering chains for the
admin-only and generic content. It's hard to say without looking at your
code, although it might be easier to secure the admin resources if they
had separate urls to the non-admin resources. A rights-checking layer
could match all of the .*/admin pages and disallow access to
unauthorised users.

Another way to approach the problem is to say that the normal page is
one resource, but the additional information is another resource
reserved for administrators. For example, you might have a div down the
bottom of the page where admin information is to be dynamically inserted
dependent on rights being granted. You could use a javascript capability
like HInclude to conditionally incorporate the admin information into
the main content. This would have caching as well as other benefits. The
pure anonymous page could be served by a completely different
application as the admin-only page if you so desired.

Benjamin.

Anne van Kesteren wrote:
> On Fri, 12 Jan 2007 12:22:25 +0100, Jerome Louvel 
> <contact@...>
> wrote:
> > That would be so nice to see such a proposal accepted for 
> HTML 5.0, in 
> > addition to adding support for PUT and DELETE actions.
> 
> FYI, Web Forms 2 which in due course will be part of the 
> HTML5 proposal already includes support for PUT and DELETE.

Any thoughts on the URI Templates?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

"omar",

you answered your own question: 

"I have a Resource."  That means in your view, it is the same
thing regardless of who is looking toward it.

Servers vary representations based on the characteristics
of the client.

Please remember that Resource is an abstraction.  Resources
don't "return" anything: your implementation does.

Walden

----- Original Message ----- 
From: "omarshariffdontlikeit" <omarshariffdontlikeit@...>
To: <rest-discuss@yahoogroups.com>
Sent: Saturday, January 13, 2007 5:30 AM
Subject: [rest-discuss] Access permissions and Resources


: Hello everyone. I'm normally a lurker but I have a quetion for the group.
: 
: Let me paint the scenario for you:
: 
: I have a Resource. If the User is anonymous, when they GET the
: Resource, the Representation returned displays one set of information.
: However, if the User if of the type Admin, the Representation returned
: displays the same information, but with additional information
: relevant to the Admin User.
: 
: My question is this: should the decision to display this different
: response data rest with the Resource, or the Representation: that is,
: should the Resource always return ALL the information, regardless of
: the User type, and let the Representation determine this information
: to be returned based on User type, or should the data the Resource
: returns be limited based on User type? The latter would, in effect
: create two Resources, whereas the first would call the same Resource,
: and filter the response based on rules defined in the Representation.
: 
: I feel that the Resource should return all the information and that it
: is the responsibility of the Representation to determine what is
: displayed. What do you guys think?
: 
: Cheers!
: 
: Ben
: 
: 
: 
: 
: __________ NOD32 1975 (20070113) Information __________
: 
: This message was checked by NOD32 antivirus system.
: http://www.eset.com
: 
:

Benjamin Carlyle wrote:
> Do you have any examples of this pattern being applied that do not
> cleanly map into standard HTTP methods?

I do and would love to learn about the design alternatives.

I have a Host service that is responsible for managing all
services/resources in the Dream environment.  There are two kinds of
interactions I find problematic to map.

The first one is blueprint registration.  A blueprint is an XML
document that tells the host what assembly/library to use and what
service definitions it contains.  Registering a blueprint is done by
sending a blueprint to:
POST /host/register

The second operation is instantiating a service.  In order to
instantiate a service, a configuration XML document must be sent to
the Host.  This is achieved by doing:
POST /host/start

In both cases, the document sent has "application/xml" as mime type. 
If another type gets sent, it is converted to "application/xml" if
possible (e.g. application/json, text/javascript, text/php, and other
supported XML mappings).

So, what would be the alternative?


- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

Alan Dean wrote:
> Don Box says that "For what it's worth, I happen to agree, as do many 
> folks I talk to in the big house."

Don is reactive, not proactive.  REST was shown over-and-over to the
Indigo team (now Windows Communication Foundation), but it was
ignored.  Why?  I don't know, but I'm assuming it was political. 
Henrik eventually left the team in disgust.


- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

On Sat, 2007-01-13 at 18:53 +0000, Steve G. Bjorg wrote:
> I have a Host service that is responsible for managing all
> services/resources in the Dream environment. There are two kinds of
> interactions I find problematic to map.
> 
> The first one is blueprint registration. A blueprint is an XML
> document that tells the host what assembly/library to use and what
> service definitions it contains. Registering a blueprint is done by
> sending a blueprint to:
> POST /host/register
> 
> The second operation is instantiating a service. In order to
> instantiate a service, a configuration XML document must be sent to
> the Host. This is achieved by doing:
> POST /host/start
> 
> In both cases, the document sent has "application/xml" as mime type. 
> If another type gets sent, it is converted to "application/xml" if
> possible (e.g. application/json, text/javascript, text/php, and other
> supported XML mappings).

I think that both of these cases sound OK on the surface, though may do
with some fine tuning. I think when you talk about your behaviour
pattern there can be exteremes in what you do. One would be to put a
method invocation into the content. Another would be to lean towards the
direction you seem to be going in these two cases. In fact, I would cast
them as two different patterns.

Let's consider the blueprint case. You want the server to store a
blueprint, so you give your blueprint to the register resource. This
actually sounds more like your container pattern. You POST the blueprint
to the factory resource. The return verb is "Created", with a location
header that points you to the created resource. You could update the
blueprint with a PUT, and deregister the blueprint by DELETE-ing the
created resource. Your server could be replaced by a range of possible
blueprint-storage systems, and the client would continue to work. It
would just issue its POST to whatever it was configured with.

Instantiation also sounds like your container pattern to me. This time
you are posting the state of a new service (which includes
configuration) to a service factory. It would create a resource to
represent the ongoing state of the service. A DELETE would destroy the
service, a PUT would change its state.

I suggest that you give some additional thought to:
* The naming of factory resources. They both mean "create state when
POSTed", and so does every other resource in the architecture. I would
just call them something like "/blueprints" and "/services".
* Your content types. You are currently indicating the file format, but
not the kind of information you are transferring in your document. File
format is important when multiple encodings of an abstract model are
permitted, but identifying the kind of information is more important. I
would be thinking along the lines of "application/something-blueprint",
"application/something-service". Though, you may need to have a
different content type for each kind of configuation you have for the
latter to really make sense.
* What happens to the state you transferrred afteer you transfer it. Is
it accessible via a new resource (Created)? Does it get mapped into the
factory resource (OK)? Or, is it swallowed by the factory resource
leaving no visible handles to work with (No Content)? All three are
normally legal, and clients should be written to deal with any one of
these being returned.

Benjamin

Benjamin Carlyle wrote:
> On Fri, 2007-01-12 at 15:23 +0200, Ittay Dror wrote:
>> this article is what prompted me to submit this thread in the first
>> place. if not, i would have probably gone the "ebay" way of defining
>> actions in the url. i also read
>> http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html in which the real architect continues the dialog from his point of view.
>>
>> what i don't like about duncan's post is that he addresses only getter
>> and setter business functions, not real ones, those that actually
>> create a process. it is very easy to say that instead of getFoo, you
>> can GET http://example.com/foo. it is harder when you want to model a
>> doSomething function.
> 
> I think this is exactly the point, though. HTTP's REST replaces the
> doSomething concept with a "make something so" concept. If you think
> about it, all doSomething can be modelled this way. Instead of "make
> this kind of state transition", just "make your state this". You have to

not every function can be modeled around state transitions. 

> get into specific examples to see how this works. The first example of
> starting or stopping a function is the same as setting a running
> resource to false or true. Do you have more examples in mind? What kind
> of process would you like to create?
> 
> The general approach to process creation would either be:
> POST a representation of the process to a factory resource to create it.
> PUT a representation of the process to the process resource to change
> its operation.
> DELETE the process to destroy it.
> PUT a false to the process's "running" resource to suspend it.
> etc ...

ok, here is my current understanding:
when you want to model a business process as REST, assuming it is an actual process, that creates information, not just a tool to manipulate one, then:
- if the BP works on a single entity, with no other parameters, then maybe it can be modeled as changing a property of that entity:
  - scheduleServiceStart(Service, Date) -> PUT date into http://example.com/service/foo/schedule

- if the BP has multiple arguments, either break to several BP:
  - scheduleService(Service, Action, Date) -> (for each action) PUT date into http://example.com/service/foo/action-schedule

- otherwise, create a ProcessManager resource and POST to it the details of the BP. maybe partition BP and create a ProcessManager for each group (scheduler for schedules, others for other actions)


is this about right?

if so, then isn't the ProcessManager a wrapper around RPC? the above process does mean that many functions inside a server can be turned to non-RPC REST API. 

> 
> Benjamin.
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

On Sun, 2007-01-14 at 07:00 +0200, Ittay Dror wrote:
> Benjamin Carlyle wrote:
> > On Fri, 2007-01-12 at 15:23 +0200, Ittay Dror wrote:
> >> this article is what prompted me to submit this thread in the first
> >> place. if not, i would have probably gone the "ebay" way of
> defining
> >> actions in the url. i also read
> http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html in which the real architect continues the dialog from his point of view.
> >> what i don't like about duncan's post is that he addresses only
> getter
> >> and setter business functions, not real ones, those that actually
> >> create a process. it is very easy to say that instead of getFoo,
> you
> >> can GET http://example.com/foo. it is harder when you want to model
> a
> >> doSomething function.
> > I think this is exactly the point, though. HTTP's REST replaces the
> > doSomething concept with a "make something so" concept. If you think
> > about it, all doSomething can be modelled this way. Instead of "make
> > this kind of state transition", just "make your state this".
> not every function can be modeled around state transitions. 

> ok, here is my current understanding:
> when you want to model a business process as REST, assuming it is an
> actual process, that creates information, not just a tool to
> manipulate one, then:
> - if the BP works on a single entity, with no other parameters, then
> maybe it can be modeled as changing a property of that entity:
> - scheduleServiceStart(Service, Date) -> PUT date into
> http://example.com/service/foo/schedule
> - if the BP has multiple arguments, either break to several BP:
> - scheduleService(Service, Action, Date) -> (for each action) PUT date
> into http://example.com/service/foo/action-schedule
> - otherwise, create a ProcessManager resource and POST to it the
> details of the BP. maybe partition BP and create a ProcessManager for
> each group (scheduler for schedules, others for other actions)

I'm not sure I understand your base assumption here. REST is just a tool
to access and manipulate a business process. However in order to
manipulate it, you have to model the process as a set of resources. This
is the same as if you were in a more general RPC environment and had to
model the process as more general objects. The goal in using resources
with their uniform interface is to invoke properties of REST, like
having your clients work with a thousand other services... controlling
the evolution of your network interface... that sort of thing. If your
system is of sufficient scale, you might even be able to see
improvements in overall system performance when you apply REST
principles.

The specific design a system should take will depend on factors that are
difficult to communicate via email. However a few options seem possible
in your example:

POST http://example.com/services/fooservice/runschedule
application/the-schedule-document-type
<vevent>
	<dtstart>some time</dtstart>
	<dtend>later time</dtend>
</vevent>

Note that PUT is designed to replace the information at a particular
resource, while POST is designed to add to it. We use POST here to add
schedule entries without destroying earlier entries. We don't need to
specify anything other than start and end time, because the rest is
handled by the context of the URL we are POSTing to. The fooservice will
run and stop at the scheduled times. You could repeat this pattern for
other services, or maintain a global/group schedule:

POST http://example.com/services/runschedule
application/the-schedule-document-type
<vevent>
	<dtstart>some time</dtstart>
	<dtend>later time</dtend>
	<url>http://example.com/services/fooservice</url>
</vevent>

This version would need to contain the extra information about what
actually needed to run.

Now when you get to action, you look like you are moving outside of the
pure REST envelope again. However you could model HTTP actions like
this:

POST http://example.com/actionschedule
application/the-schedule-document-type
<vevent>
	<dtstart>some time</dtstart>
	<action>
		<method>PUT</method>
		<url>http://example.com/services/fooservice</url>
		<document type="application/the-document-type">
			<state>running</state>
			<configuration>....</configuration>
			...
		</document>
	</action>
</vevent>

> if so, then isn't the ProcessManager a wrapper around RPC? the above
> process does mean that many functions inside a server can be turned to
> non-RPC REST API. 

In REST we typically expose the interface to our services as information
rather than arbitrary method invocations with names hidden in urls or
content. It can be a pretty serious rethink to consider what information
you are providing to users for access and update, rather than what
methods the users may want to invoke. There are often mismatches that
make it difficult to do this as an API, but momentum that makes it just
as difficult to change things internally to match the REST approach.
Somtimes the best you can do is apply the best principles to new softare
and see how it goes for a while before even thinking about a retrofit.

In the end you have to consider whether REST is valuable enough in your
environment to offset the cost. In small well-controlled environments it
often won't be. If the scale of your operation is larger it may start to
pay for itself in reduced coordination costs internally.

Benjamin.

I'm looking for some feedback on URI patterns.  I just recently found
out about URI templates [1] and have been scratching my head on how
they could be extended to also provide URI patterns.

For example:
http://server/{first}/{last}

This URI could be used to produce or consume a URI such as:
http://server/john/doe

However, the template syntax doesn't work for matching query parameters:
http://server/{first}/{last}?maxcount={maxrecords}&offset={offset}

In this case, producing an URI is simple, but for using it as a
pattern, a few questions arise:
* How would one indicate that 'maxcount' and 'offset' are optional
parameters?
* How would one indicate that they are mandatory?


How about using brackets to identify optional parameters?
http://server/{first}/{last}?[maxcount={maxrecords}]&offset={offset}

Would it make sense to combine them?  For example to indicate that
both parameters are needed or neither?
http://server/{first}/{last}?[maxcount={maxrecords}&offset={offset}]

How about either/or choices using vertical bar (|)?
http://server/{first}/{last}?[maxcount={maxrecords}&[offset={offset}|page={page}]]

Does this make sense?  How have you dealt with matching URIs?


Cheers,

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org


[1] http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-00.txt

I'm more interested in the generation of URI, rather than the parsing as I
would use regular expressions to parse.
It would be very handy to have the URI templates support indicating optional
output, especially for query terms.
 

> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Steve G. Bjorg
> Sent: Monday, January 15, 2007 12:04 PM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] URI Templates & Patterns
> 
> I'm looking for some feedback on URI patterns.  I just 
> recently found out about URI templates [1] and have been 
> scratching my head on how they could be extended to also 
> provide URI patterns.
> 
> For example:
> http://server/{first}/{last}
> 
> This URI could be used to produce or consume a URI such as:
> http://server/john/doe
> 
> However, the template syntax doesn't work for matching query 
> parameters:
> http://server/{first}/{last}?maxcount={maxrecords}&offset={offset}
> 
> In this case, producing an URI is simple, but for using it as 
> a pattern, a few questions arise:
> * How would one indicate that 'maxcount' and 'offset' are 
> optional parameters?
> * How would one indicate that they are mandatory?
> 
> 
> How about using brackets to identify optional parameters?
> http://server/{first}/{last}?[maxcount={maxrecords}]&offset={offset}
> 
> Would it make sense to combine them?  For example to indicate 
> that both parameters are needed or neither?
> http://server/{first}/{last}?[maxcount={maxrecords}&offset={offset}]
> 
> How about either/or choices using vertical bar (|)?
> http://server/{first}/{last}?[maxcount={maxrecords}&[offset={o
> ffset}|page={page}]]
> 
> Does this make sense?  How have you dealt with matching URIs?
> 
> 
> Cheers,
> 
> - Steve
> 
> --------------
> Steve G. Bjorg
> http://www.mindtouch.com
> http://www.opengarden.org
> 
> 
> [1] 
> http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-00.txt
> 
> 
> 
>  
> Yahoo! Groups Links
> 
> 
> 

Hi,

I'd like to continue the question Matthais asked regarding updating
composite and individual resources.  I think I basically have the same
question myself and would like to know if this approach might be
considered Un-RESTful?

To add another example, I'm looking at building a RESTful mortgage
application system; its resources might look something like this:

Application
--Applicants
----Applicant
------Address
------EmploymentHistory
------FinancialHistory
--PropertyDetails
----Address
etc...

I can see two ways that our customers may want to use the system:

1) Navigate through the resources, following each link, adding more
and more information as they go.

or

2) Send all the data in one go. Or as much as they have available,
perhaps returning later to navigate through and fill in the gaps.

To accommodate both scenarios a POST to /Application could examine the
amount of data that was sent and create a varying number of child
resources accordingly.

I feel like it "smells a bit" because a GET to /Application would
return a different (i.e. shorter) representation than that which can
be POSTed back.

Does anyone consider this kind of approach to be Un-RESTful?   If so,
why, and any suggestions on how it can be made more RESTful?


--- In rest-discuss@yahoogroups.com, "Ernst, Matthias"
<matthias.ernst@...> wrote:
>
> Hi,
> 
> one of the cornerstones of RESTful design is the concept of
> hierarchy and containment - such as POST in the sense of "insert new
child".
> 
> I'm trying to make use of this for the configuration of a hierarchical
> service container about as follows:
> 
> GET /container  :  answer a representation of the container's
configuration (port, max threads, ...) including links to all services
> PUT /container :   reconfigure the container
> 
> POST /container:   add service
> GET /container/{service}:  answer service configuration
> PUT /container/{service}:  add/reconfigure service
> DELETE /container/{service}: remove service
> 
> So far so good. However, I'm unsure about the significance of the
service configuration links in the container resource. PUTting to the
container resource with fewer service links, should that indicate the
deletion of a service? Or should I ignore those?
> 
> Also, I'd like to GET/PUT the _entire_ configuration (container +
services) in one representation, i.e. one that contains the service
configurations in the container configuration instead of links.
> PUTting that representation to /container would then also create,
reconfigure or delete services.
> 
> How would you represent that? A different URI? A different
MIME-Type? GET /container with accept:
application/entireconfiguration+xml vs
application/containerconfiguration+xml
> 
> Or I could use the same mime type but make the child representations
optional in the schema: GET /container always includes the service
configurations including their individual links, embedded in a
<services> element. PUTting a representation that does not include
said <services> element would only update the container resource.
Including the <services> element would indicate that I want to
configure all services at once, too.
> 
> Does that make sense to you?
> 
> Thanks
> Matthias
>

Ittay Dror:

  > this article is what prompted me to submit this thread in the first
  > place. if not, i would have probably gone the "ebay" way of defining
  > actions in the url. i also read
  > 
http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html 

  > in which the real architect continues the dialog from his point of view.

  > what i don't like about Duncan's post is that he addresses only getter
  > and setter business functions, not real ones, those that actually
  > create a process. it is very easy to say that instead of getFoo, you
  > can GET http://example.com/foo.
  > it is harder when you want to model a doSomething function.

Part 3 of the series has a discussion of these 'real business functions' 
that go beyond simple reading and writing, or getting and setting, data 
on the server.



Anyway, thanks for reading my dialogue articles! I have been hesitant to 
notify this list of their existence because: (a) they're not complete 
yet, and (b) they may be seen as a challenge to the direction that REST 
has gone towards the CRUD view since The Thesis, and I don't want to be 
seen as in any way confrontational.

Plus, I'm aware that I got a ton of traffic to my blog via a kind link 
from DHH - and he has just converted Rails to CRUD-REST...  =0/

However, now I've been linked to on the list itself, I suppose it's 
pointless not coming over here and defending myself.



So - I promote a /symmetric/ REST point of view, with active resources 
being dependent on each other and conveying state between themselves 
with either GET or POST depending on which party initiates the transfer.

I do hope and believe this pattern is still REST-compatible. Please read 
part 3 of my series 
(http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/) 
for more explanation of this pattern.

Of course, I probably end up thereby promoting POST idempotency, but I 
see that as a good thing. Example: if you've added something to a list, 
adding it again doesn't do anything. For some function same(resx,resy), 
of course.



Now, Benjamin Carlyle, who should always be heeded, said:

> .. REST replaces the doSomething concept with a "make something so"
> concept. If you think about it, all doSomething can be modelled
> this way. .. "make your state this". 

This is an example of what I currently call (in my grubby lab notebook) 
a 'transformation intent' - where some party expresses directly to a 
resource that they'd like some state to become manifest in or perhaps 
around that target resource.

My heresy (maybe evolution, then) is that I don't see the future of REST 
being constrained to resources responding to such transformation intents 
of other parties: I see some (most!) resources transforming /themselves/ 
in reaction to the state of /other/, peer resources.  Allow me to 
elaborate..


I break REST interaction down into three modes - from dumb to smart, via 
dependent:

-: If a resource receives such a direct transformation request or 
intent, it may be *dumb* and go ahead and do just what it's told, 
whenever it's told. That's what I was talking about in parts 1 and 2 of 
the dialogues. It's a bit like a database. I'd still do without PUT and 
DELETE, mind, to prevent it being seen that way!

-: Alternatively - what seems to be the subject of this thread - it may 
have *real-world dependency*: maybe it can't just switch to 'running' 
until the real world thing it models actually /is/ running!  So, when it 
receives a direct transformation intent, it goes off and satisfies that 
constraint by ensuring it's ticking over in reality, and only then 
changes its visible state to 'running'.

-: Finally, the resource may be *smart*, and decide to switch to 
'running' because of the rule that, as long as Joe's resource is 
running, it should be running itself. So it spots Joe's resource 
running, and starts running without even being told to!  That's what I 
was talking about in part 3 of my dialogues.



The latter is advanced REST programming in transformation rules, I 
suppose.  Spontaneous transformation without any direct transformation 
intent - indirect implication or even deduction.

I haven't directly covered the middle - hidden real-world 
responsibilities - case so far in my article series. I didn't think 
settable resources with non-disk-state side-effects were sufficiently 
common in the usual REST integration world to warrant coverage as yet!

Except insofar as it's implied by the first - dumb - case, in that the 
visible state of a resource obviously shouldn't be set to something for 
everyone to see until it's actually saved in that state on disk. I also 
alluded to this sort of thing when talking about email side effects in 
part 3.

A printer comes to mind as another example of such a resource: you may 
want to take it offline by requesting online/offline state. A print 
queue resource is related to this.

An example which is /not/ like this is a user interface, which 'watches' 
other state rather than being told what state to achieve directly, and 
is more like the third, smart, dependent resource, case above.

(Actually, in Second Life, I think someone can push your 'avatar 
resource' and directly change what you can see, but now we're really 
looking ahead to the future of REST!)


I'll get to these examples later in my series. Which may now need to be 
ten parts  =0(

Meanwhile, I'd be delighted to hear what you - Roy Fielding - have to 
say about all this...  =0)

Cheers!

Duncan

_________________________________
Duncan Cragg
http://duncan-cragg.org/blog/

Steve G. Bjorg wrote:
> I'm looking for some feedback on URI patterns.  I just 
> recently found out about URI templates [1] and have been 
> scratching my head on how they could be extended to also 
> provide URI patterns.

FYI, the list to discuss URI Templates is [uri@...].  URI Templates is a
great piece of work.

> For example:
> http://server/{first}/{last}
> 
> This URI could be used to produce or consume a URI such as:
> http://server/john/doe
> 
> However, the template syntax doesn't work for matching query 
> parameters:
> http://server/{first}/{last}?maxcount={maxrecords}&offset={offset}
> 
> In this case, producing an URI is simple, but for using it as 
> a pattern, a few questions arise:
> * How would one indicate that 'maxcount' and 'offset' are 
> optional parameters?
> * How would one indicate that they are mandatory?
>
> How about using brackets to identify optional parameters?
> http://server/{first}/{last}?[maxcount={maxrecords}]&offset={offset}
> 
> Would it make sense to combine them?  For example to indicate 
> that both parameters are needed or neither?
> http://server/{first}/{last}?[maxcount={maxrecords}&offset={offset}]

I'm pretty sure the syntax for option is a trailing question mark within the
braces, i.e.:

	http://server/{first}/{last}?maxcount={maxrecords?}&offset={offset?}

The idea here is that if maxrecords is null then all of
"maxcount={maxrecords?}" would be omitted  and same for offset  (I think. I
hope.)   

> 
> How about either/or choices using vertical bar (|)?
>
http://server/{first}/{last}?[maxcount={maxrecords}&[offset={offset}|page={p
age}]]
> 

I had proposed a comma, but since I proposed it occurred to me that a
vertical bar would be more consistent with other languages use of an "or"
operator so to me, yes it makes sense.

That said, I cc'd [uri@...]; you can review the archive and sign up at
[1].

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org/
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

[1] http://lists.w3.org/Archives/Public/uri/

Duncan Cragg wrote:
> 
> 
> Ittay Dror:
> 
>  > this article is what prompted me to submit this thread in the first
>  > place. if not, i would have probably gone the "ebay" way of defining
>  > actions in the url. i also read
>  >
> http://addsimplicit y.typepad. com/adding_ simplicity_ an_engi/2006/ 
> 11/the_rest_ dialog.html 
> <http://addsimplicity.typepad.com/adding_simplicity_an_engi/2006/11/the_rest_dialog.html> 
> 
> 
>  > in which the real architect continues the dialog from his point of view.
> 
>  > what i don't like about Duncan's post is that he addresses only getter
>  > and setter business functions, not real ones, those that actually
>  > create a process. it is very easy to say that instead of getFoo, you
>  > can GET http://example. com/foo. <http://example.com/foo.>
>  > it is harder when you want to model a doSomething function.
> 
> Part 3 of the series has a discussion of these 'real business functions'
> that go beyond simple reading and writing, or getting and setting, data
> on the server.

good article.

let's see if i got it right: the difference of REST design vs RPC (SOAP) is that in REST, the client states what the final state of the resource should be, and the server does whatever it needs to accomplish that. in RPC, the client initiates a process which can change states as it progresses.

if this is true, what happens if the server can't reach the declared state? e.g., i have a printer, which i want to put online. i can POST/PUT 'online' to http://example.org/printers/pr1/status. but what if the actual process of making the physical printer fails? won't it be confusing if http://example.org/printers/pr1/status changes to 'error' by the server? it means the client can't be sure that what he posted stays. furthermore, once you allow both the server and client to modify resources, there's a risk of races. (or, maybe the part of the server that changes the resource can be thought of as a client?)

> 
> Anyway, thanks for reading my dialogue articles! I have been hesitant to
> notify this list of their existence because: (a) they're not complete
> yet, and (b) they may be seen as a challenge to the direction that REST
> has gone towards the CRUD view since The Thesis, and I don't want to be
> seen as in any way confrontational.
> 
> Plus, I'm aware that I got a ton of traffic to my blog via a kind link
> from DHH - and he has just converted Rails to CRUD-REST... =0/
> 
> However, now I've been linked to on the list itself, I suppose it's
> pointless not coming over here and defending myself.
> 
> So - I promote a /symmetric/ REST point of view, with active resources
> being dependent on each other and conveying state between themselves
> with either GET or POST depending on which party initiates the transfer.
> 
> I do hope and believe this pattern is still REST-compatible. Please read
> part 3 of my series
> (http://duncan- cragg.org/ blog/post/ business- functions- 
> rest-dialogues/ 
> <http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/>)
> for more explanation of this pattern.
> 
> Of course, I probably end up thereby promoting POST idempotency, but I
> see that as a good thing. Example: if you've added something to a list,
> adding it again doesn't do anything. For some function same(resx,resy) ,
> of course.
> 
> Now, Benjamin Carlyle, who should always be heeded, said:
> 
>  > .. REST replaces the doSomething concept with a "make something so"
>  > concept. If you think about it, all doSomething can be modelled
>  > this way. .. "make your state this".
> 
> This is an example of what I currently call (in my grubby lab notebook)
> a 'transformation intent' - where some party expresses directly to a
> resource that they'd like some state to become manifest in or perhaps
> around that target resource.
> 
> My heresy (maybe evolution, then) is that I don't see the future of REST
> being constrained to resources responding to such transformation intents
> of other parties: I see some (most!) resources transforming /themselves/
> in reaction to the state of /other/, peer resources. Allow me to
> elaborate..
> 
> I break REST interaction down into three modes - from dumb to smart, via
> dependent:
> 
> -: If a resource receives such a direct transformation request or
> intent, it may be *dumb* and go ahead and do just what it's told,
> whenever it's told. That's what I was talking about in parts 1 and 2 of
> the dialogues. It's a bit like a database. I'd still do without PUT and
> DELETE, mind, to prevent it being seen that way!
> 
> -: Alternatively - what seems to be the subject of this thread - it may
> have *real-world dependency*: maybe it can't just switch to 'running'
> until the real world thing it models actually /is/ running! So, when it
> receives a direct transformation intent, it goes off and satisfies that
> constraint by ensuring it's ticking over in reality, and only then
> changes its visible state to 'running'.
> 
> -: Finally, the resource may be *smart*, and decide to switch to
> 'running' because of the rule that, as long as Joe's resource is
> running, it should be running itself. So it spots Joe's resource
> running, and starts running without even being told to! That's what I
> was talking about in part 3 of my dialogues.
> 
> The latter is advanced REST programming in transformation rules, I
> suppose. Spontaneous transformation without any direct transformation
> intent - indirect implication or even deduction.
> 
> I haven't directly covered the middle - hidden real-world
> responsibilities - case so far in my article series. I didn't think
> settable resources with non-disk-state side-effects were sufficiently
> common in the usual REST integration world to warrant coverage as yet!
> 
> Except insofar as it's implied by the first - dumb - case, in that the
> visible state of a resource obviously shouldn't be set to something for
> everyone to see until it's actually saved in that state on disk. I also
> alluded to this sort of thing when talking about email side effects in
> part 3.
> 
> A printer comes to mind as another example of such a resource: you may
> want to take it offline by requesting online/offline state. A print
> queue resource is related to this.
> 
> An example which is /not/ like this is a user interface, which 'watches'
> other state rather than being told what state to achieve directly, and
> is more like the third, smart, dependent resource, case above.
> 
> (Actually, in Second Life, I think someone can push your 'avatar
> resource' and directly change what you can see, but now we're really
> looking ahead to the future of REST!)
> 
> I'll get to these examples later in my series. Which may now need to be
> ten parts =0(
> 
> Meanwhile, I'd be delighted to hear what you - Roy Fielding - have to
> say about all this... =0)
> 
> Cheers!
> 
> Duncan
> 
> ____________ _________ _________ ___
> Duncan Cragg
> http://duncan- cragg.org/ blog/ <http://duncan-cragg.org/blog/>
> 
> 


-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

On Jan 13, 2007, at 2:30 PM, Benjamin Carlyle wrote:

> Let's consider the blueprint case. You want the server to store a
> blueprint, so you give your blueprint to the register resource. This
> actually sounds more like your container pattern. You POST the  
> blueprint
> to the factory resource. The return verb is "Created", with a location
> header that points you to the created resource. You could update the
> blueprint with a PUT, and deregister the blueprint by DELETE-ing the
> created resource. Your server could be replaced by a range of possible
> blueprint-storage systems, and the client would continue to work. It
> would just issue its POST to whatever it was configured with.

This is so obvious that I'm stunned I missed it.  Blueprints should  
definitively be modeled as a container.

> Instantiation also sounds like your container pattern to me. This time
> you are posting the state of a new service (which includes
> configuration) to a service factory. It would create a resource to
> represent the ongoing state of the service. A DELETE would destroy the
> service, a PUT would change its state.

There is a key difference with instantiation.  In the case of  
blueprints, adding a blueprints did result in the creation of sub- 
resource.
Example:
http://server/host/blueprints/my_new_blueprint

However, in the case of instantiation, there is no sub-resource  
assumption.  Thus, the location of the new service could be:
http://server/my_new_service

I think the sub-resource relationship is key to the container  
patters, because it defines scope of influence.  However, I can't  
apply this restriction to the Host service, which is peer to other  
services.

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

[ Attachment content not displayed ]

I searched but had a hard time isolating a similar topic...

I'm working a rest based application and am struggling with the
challenge of when to return a resource for edit (if a form) vs when to
simply return the resource. I could always present the content in a
form  if the user is authorized, but this poses a couple of challenges:
- additional overhead of populating selection lists when not needed
- user may worry that than have changed something when that was not
their intent.

-Does somebody have experience that would suggest a different URI
structure for when doing a GET to edit a resource?
-Would it be appropriate to pass a parameter in this case, ie ?edit=yes

Thanks,

Hi David,

> -Does somebody have experience that would suggest a different URI
> structure for when doing a GET to edit a resource?
> -Would it be appropriate to pass a parameter in this case, ie ? 
> edit=yes

I don't know if this is the "right" answer, but that's the way that  
Rails 1.2 does it:

http://topfunky.com/clients/peepcode/REST-cheatsheet.pdf

Though they use ";edit" as the modifier, to distinguish from queries.

-enp


On Jan 16, 2007, at 11:41 AM, david.nusbaum wrote:

> I searched but had a hard time isolating a similar topic...
>
> I'm working a rest based application and am struggling with the
> challenge of when to return a resource for edit (if a form) vs when to
> simply return the resource. I could always present the content in a
> form if the user is authorized, but this poses a couple of challenges:
> - additional overhead of populating selection lists when not needed
> - user may worry that than have changed something when that was not
> their intent.
>
> -Does somebody have experience that would suggest a different URI
> structure for when doing a GET to edit a resource?
> -Would it be appropriate to pass a parameter in this case, ie ? 
> edit=yes
>
> Thanks,
>
>
> 

"david.nusbaum" <david.nusbaum@...> writes:

> -Does somebody have experience that would suggest a different URI
> structure for when doing a GET to edit a resource?
> -Would it be appropriate to pass a parameter in this case, ie
> ?edit=yes

I struggled with this for a while with the app that I am working on.

I choose to send the "gui" with any authorized request. I usually have
an edit button that displays the gui.

It works very well.

Authenticated people are not such a caching concern anyway (because
they're authenticated it's often the case that the content can't be
cached). And it feels more natural to have a single resource
controlling it's own destiny as it were.


I'll be showing people my app this week so you'll be able to see this
working, even if it's still a bit rough and ready.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Tue, 2007-01-16 at 19:41 +0000, david.nusbaum wrote:
> I'm working a rest based application and am struggling with the
> challenge of when to return a resource for edit (if a form) vs when

You return representations, not resources.

It might make it less confusing to realize that it is the "view" and
"edit" representations that are separate, not the resource.


> -Does somebody have experience that would suggest a different URI
> structure for when doing a GET to edit a resource?
> -Would it be appropriate to pass a parameter in this case,
> ie ?edit=yes

Sure.

- GET /wiki/foo
- [click edit]
- GET /wiki/foo?mode=edit
  (or /wiki/foo/editable, or /wiki/foo;edit, or...)
- [make changes]
- POST /wiki/foo

Seems pretty webby and RESTful to me.

-- 
...jsled
http://asynchronous.org/ - a=jsled;b=asynchronous.org;echo ${a}@${b}

Josh Sled wrote:
> On Tue, 2007-01-16 at 19:41 +0000, david.nusbaum wrote:
>> I'm working a rest based application and am struggling with the
>> challenge of when to return a resource for edit (if a form) vs when
> 
> You return representations, not resources.
> 
> It might make it less confusing to realize that it is the "view" and
> "edit" representations that are separate, not the resource.

IMO it's perfectly acceptable to have a resource which allows one to 
edit another resource, and which therefore return representations to and 
from different URIs.

"Joe Gregorio" <joe@...> writes:

> As long as we are being brutally honest about how things work
> in *the real world*, I'll just point out that if some VP
> discovered that he couldn't edit his blog from his shiny new Nokia phone
> because the proxy server blocked PUT requests, then that proxy would
> get changed so fast it would make your eyes bleed.

Maybe things are different in the states, but here in the UK the idea
of a VP who edits his blog from his mobile phone is something of a
fiction.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On 1/9/07, Nic James Ferrier <nferrier@...> wrote:
>
>  I think Elliotte is correct that we could fix the problem by getting
>  the proxy makers to change their proxies.
>
>  However, how long would it take to fix the problem. The big
>  organization that I was referring to had (amongst others) a Novell
>  Netware proxy server. It was at least 10 years old.
>
>  I recently made a trip to a medium sized company who were still using
>  Microsoft Proxy Server 1.0. I don't even want to think about how old
>  that is.

As long as we are being brutally honest about how things work
in *the real world*, I'll just point out that if some VP
discovered that he couldn't edit his blog from his shiny new Nokia phone
because the proxy server blocked PUT requests, then that proxy would
get changed so fast it would make your eyes bleed.

To put this in perspective we're talking about a configuration
option on an HTTP proxy/firewall in a company that 11 years
ago was probably running SNA over token ring. To pretend that
things will stay the same as they are today is, at best, delusional.

   -joe

-- 
Joe Gregorio        http://bitworking.org

Which HTTP method should be used for safe but confidential operations, 
in which the query string might reveal data. For example, requesting the 
current balance for a credit card:

http://www.bank.com/statements?number=1234567890984567

Assume HTTP authentication is being used, but we might still wish to 
avoid shoulder surfing.

Is it acceptable to use POST here to hide the number from prying eyes, 
or should this still be GET? Why or why not?

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Elliotte Harold <elharo@...> writes:

> Which HTTP method should be used for safe but confidential operations, 
> in which the query string might reveal data. For example, requesting the 
> current balance for a credit card:
>
> http://www.bank.com/statements?number=1234567890984567
>
> Assume HTTP authentication is being used, but we might still wish to 
> avoid shoulder surfing.
>
> Is it acceptable to use POST here to hide the number from prying eyes, 
> or should this still be GET? Why or why not?

It should be GET.

Your credit card number isn't secret. You hand it over to all sorts of
strangers every day.

To address the point of shoulder surfing: if someone is standing
behind you at an ATM looking over your shoulder do you:

a) carry on typing in your pin?
b) turn round, write the pin on a piece of paper and give to the
surfer?
c) stop entering your pin, even if you have to go to another machine
somewhere else?

And when you get your statement are you still going to be standing
there with the shoulder surfer? Because the resource you're looking at
may well have the account number in it. How are you going to stop them
looking at that? Maybe a sudden distraction? try throwing a cat across
the table.


I've been asked these sorts of things a lot by people connected with
projects. They all seem to come from a desire to be secure... but with
no realistic view of security. Security through obscurity is no
security etc...

The really bad thing about things like that is that they cause
architectural problems. I have many times come to a developed system
that is broken architecturally only to find out that underlying the
break is something spurious that is the way it is because "it just
is". Inevitably, it's something like the above.


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Elliotte Harold wrote:
> Which HTTP method should be used for safe but confidential operations, 
> in which the query string might reveal data. For example, requesting the 
> current balance for a credit card:
> 
> http://www.bank.com/statements?number=1234567890984567
> 
> Assume HTTP authentication is being used, but we might still wish to 
> avoid shoulder surfing.
> 
> Is it acceptable to use POST here to hide the number from prying eyes, 
> or should this still be GET? Why or why not?

Surely the protocol should be HTTPS not HTTP for such a request? GET
should be fine under such circumstances.
-- 
Chris Burdess

Elliotte Harold wrote:
> Which HTTP method should be used for safe but confidential operations, 
> in which the query string might reveal data. For example, requesting the 
> current balance for a credit card:
> 
> http://www.bank.com/statements?number=1234567890984567

I'd probably build that *completely* differently so that the number used 
for identification was not the credit card number.

At a more general level though:

When GET is used over HTTPS the SSL is happening at a lower level than 
the HTTP (for which reason if HTTPS were registered today it would 
probably be denied a port number and the IETF would insist that a 
different mechanism were used to indicate that an encrypted transport 
protocol was being used underneath the HTTP - the rule against separate 
port number assignments for "Secure form of X" wasn't in place when 
HTTPS came on the scene though).

Therefore https://www.bank.com/statements?number=1234567890984567 is 
safe at the transport level.

https://www.bank.com/statements/3r421 where 3r421 identifies the account 
which uses the credit card number 1234567890984567 is safer still.

Of course "safe" assumes other reasonable precautions are taken.

On 1/19/07, Nic James Ferrier <nferrier@...> wrote:
> Elliotte Harold <elharo@...> writes:
>
>  > Which HTTP method should be used for safe but confidential operations,
>  > in which the query string might reveal data. For example, requesting the
>  > current balance for a credit card:
>  >
>  > http://www.bank.com/statements?number=1234567890984567
>  >
>  > Assume HTTP authentication is being used, but we might still wish to
>  > avoid shoulder surfing.
>  >
>  > Is it acceptable to use POST here to hide the number from prying eyes,
>  > or should this still be GET? Why or why not?
>
>  It should be GET.

Seems a bit pendantic. Just because GET is defined to be safe does not
mean you cannot do safe operations with POST.  And the benefits of GET
(e.g. cacheability) don't seem to apply here.

Bob Haugen wrote:
> Seems a bit pendantic. Just because GET is defined to be safe does not
> mean you cannot do safe operations with POST.  And the benefits of GET
> (e.g. cacheability) don't seem to apply here.

That's not the only benefit of GET and caching could apply - not a 
shared cache obviously, but a secure private cache isn't an impossibility.

You can do safe operations with POST, but code blocking all potentially 
unsafe operations would block it.

On Jan 19, 2007, at 5:26 AM, Chris Burdess wrote:

> Elliotte Harold wrote:
>> Which HTTP method should be used for safe but confidential  
>> operations,
>> in which the query string might reveal data. For example,  
>> requesting the
>> current balance for a credit card:
>>
>> http://www.bank.com/statements?number=1234567890984567
>>
>> Assume HTTP authentication is being used, but we might still wish to
>> avoid shoulder surfing.
>>
>> Is it acceptable to use POST here to hide the number from prying  
>> eyes,
>> or should this still be GET? Why or why not?
>
> Surely the protocol should be HTTPS not HTTP for such a request? GET
> should be fine under such circumstances.
>
One other place the credit card number will show up, though, is in  
the browser's history. If someone were to use this from a public  
terminal and not clear the history, then the next person along could  
get the credit card number by looking at the history. Thus I'd lean  
towards some other approach, such as POST the credit card number, and  
redirect to a GET that includes a different "surrogate" number, not  
the credit card number, that on the server is mapped to the credit  
card account. The user would need to authenticate to be able to see  
that page, so even though that surrogate number would be visible in  
the browser cache, someone else who came along wouldn't be able to  
access it unless the previous fellow forgot to log out. (Which is  
still a possibility.)

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Chris Burdess wrote:

> Surely the protocol should be HTTPS not HTTP for such a request? GET
> should be fine under such circumstances.

That only solves the Bob problem. It does nothing about Dave standing 
around watching Alice read her screen.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On Fri, Jan 19, 2007 at 07:52:20AM -0500, Elliotte Harold wrote:
> Which HTTP method should be used for safe but confidential operations, 
> in which the query string might reveal data. For example, requesting the 
> current balance for a credit card:
> 
> http://www.bank.com/statements?number=1234567890984567
> 
> Assume HTTP authentication is being used, but we might still wish to 
> avoid shoulder surfing.

> Is it acceptable to use POST here to hide the number from prying eyes, 
> or should this still be GET? Why or why not?

I think that you should still be using GET here. However, you could
encrypt the query-string in order to render it unusable without the key,
then decrypt on the appserver. Ideally, the key would be based on
criteria that would be hard to reproduce, eg: session start time,
session id, IP address, &c.
-- 
Ceri Storey <cez@...>
'What I really want is "apt-get smite"' 
    --Rob Partington
http://unix.culti.st/

On Fri, 2007-01-19 at 15:10 +0000, Jon Hanna wrote:
> Bob Haugen wrote:
> > Seems a bit pendantic. Just because GET is defined to be safe does
> not
> > mean you cannot do safe operations with POST. And the benefits of
> GET
> > (e.g. cacheability) don't seem to apply here.
> 
> That's not the only benefit of GET and caching could apply - not a 
> shared cache obviously, but a secure private cache isn't an
> impossibility.
> 
> You can do safe operations with POST, but code blocking all
> potentially 
> unsafe operations would block it.

It seems that Jon Hanna hit the nail on the head by suggesting secret
data should be substituted for a non-secret hash when used in
identifiers. However, I suggest that secure communications is one of
those areas where the assumptions that REST are based on do not hold so
tightly.

Secret data has fewer scalability concerns than widely known data,
because secrecy itself is not scalable. You don't expect a million or
even a thousand clients to all ask for the statement on a particular
credit card. You expect maybe 10 hits per day for a busy account. If a
lot of people have access to a particular secret, it isn't very secret.
This is why SSL is often the right answer to secure messaging, despite
limiting the application of caches and the use of intermediataries for
other purposes.

Benjamin

On Tue, 2007-01-16 at 17:07 -0500, Josh Sled wrote:
> On Tue, 2007-01-16 at 19:41 +0000, david.nusbaum wrote:
> > I'm working a rest based application and am struggling with the
> > challenge of when to return a resource for edit (if a form) vs when
> You return representations, not resources.
> It might make it less confusing to realize that it is the "view" and
> "edit" representations that are separate, not the resource.

I would argue that the reason for having different representations
available from a resource is to provide different levels of semantic
fidelity based on client capabilities. Across these representations I
would expect essentially the same information to be returned.

Here, I think you are talking about one representation that returns
resource content and another representation that returns a form to edit
that content. Both representations would presumably be HTML, so they
don't sound like representations of the same resource. They convey
different information using the same content type. It sounds like they
would require different urls. The two resources are related. It is
likely the share state on the server. However, hyperlinking to one is a
very different matter than hyperlinking to the other.

You indicate as such here:
> - GET /wiki/foo
> - [click edit]
> - GET /wiki/foo?mode=edit
>   (or /wiki/foo/editable, or /wiki/foo;edit, or...)
> - [make changes]
> - POST /wiki/foo

An alternative design would be to include the edit form as part of the
main representation, perhaps with its visible attribute set to false
when javascript is available. A javascript toggle on the page might make
the edit form visible and allow submission back to the server. This
single response document design would only need one url.

Benjamin.

G'day,

I have been thinking about the idempotency of POST lately, and the
exchange with Steve Bjorg has prompted me to write about it. My current
direction is to treat a POST of null to a factory resource as
idempotent.

A null POST to a factory resource would create a resource that could be
PUT to safely. Either the null POST or the PUT could be repeated safely
if they time out. I'm cautious about using the POE specification due to
the way that it seems to use up the POST method for the created
resource, and doesn't really define a method for creating the temporary
resource in the first place. Null POST idempotency seems to me to be an
appropriate way of thinking about the problem: Add no state to be
demarcated by a temporary resource, then replace that null state with
the content I would have otherwise POSTed. The PUT also converts the
temporary resource into a resource with a normal lifetime.

Potential issues:

1. Idempotency of null POST
My biggest concern is about encoding the idempotency assumption into the
client. If it happened to be unsafe for a particular server, the client
could trigger unfortunate behaviour. For this reason it may be useful to
introduce a new method that performs this setup. I'm thinking something
like PREPARE might be appropriate.

2. Temporary Resource lifetime
Temporary resources would need to expire after some time to allow the
server to reclaim memory and other... well... resources. I suggest that
a rough timer would be the simplest approach: Sweep every 40s and
destroy temporary resources that are still present from the last sweep.
The exact mechanism and timing would be up to the server.

3. Temporary Resources cleaned up too soon
The client behaviour on seeing a 404 come back from PUT might be an
issue. Did the PUT succeed and has the resource been destroyed by normal
means, or did the resource timeout before a successful PUT? It may be
necessary to prevent a live resource from being converted to a 404 too
quickly. Perhaps keeping a 410 up for at least the normal lifetime of
the temporary would indicate to the client that its earlier PUT was
successful. This temporary resource lifetime would have to be long
enough to ensure all reasonable client activity worked correctly. If the
client sees a 404 it has no option but to return an error to its user
indicating that it doesn't know whether the PUT occured or not.

4. Overconsumption of server-side state
The final question is how to deal with clients that issue too many
PREPARE requests, thereby consuming unreasonable quanitities of
server-side resources. It may be important to impose a maximum PREPARE
rate based on source IP or other request characteristic.

Thoughts?

Benjamin.

Steve,

On Tue, 2007-01-16 at 07:05 -0800, Steve Bjorg wrote:
> On Jan 13, 2007, at 2:30 PM, Benjamin Carlyle wrote:
> > Instantiation also sounds like your container pattern to me. This
> time
> > you are posting the state of a new service (which includes
> > configuration) to a service factory. It would create a resource to
> > represent the ongoing state of the service. A DELETE would destroy
> the
> > service, a PUT would change its state.
> There is a key difference with instantiation. In the case of 
> blueprints, adding a blueprints did result in the creation of sub- 
> resource.
> Example:
> http://server/host/blueprints/my_new_blueprint
> However, in the case of instantiation, there is no sub-resource 
> assumption. Thus, the location of the new service could be:
> http://server/my_new_service
> I think the sub-resource relationship is key to the container 
> patters, because it defines scope of influence. However, I can't 
> apply this restriction to the Host service, which is peer to other 
> services.

Maybe to a human designer on the server side, but in practice from all
perspectives... I don't think so. You might want to give the pattern a
different name when the resources aren't given a subpath under the
factory resource, but the mechanism and concept is the same. For this
reason I usually talk about factories rather than containers. The state
may be demarcated by resources hosted under the factory's path, or
elsewhere (Created). The new state may be added to the factory resource
directly, or given no client-visible handle at all (OK, or No Content).

I have heard about the container pattern described several times, but it
only really makes sense when we don't arbitrarily require new resources
to live under the resource we POSTed to. Clients certainly can't assume
it will be so. The semantics of POST don't include the restriction, and
it is inadvisible to communicate to the client that they can make the
assumption. After all, you might change your mind later.

The Location header in a POST could direct the client anywhere. It might
be a partner website. It might contain an authority that takes the
client to a different server cluster within your data centre. The client
may choose not to apply the same trust metrics to a new authority, or
even to a different path structure under the same authority. The server
should take this into account as part of the design. However, the
freedom to decide where the new resource goes is part of the prerogative
of the server.

Benjamin.

On Tue, 2007-01-16 at 09:11 +0200, Ittay Dror wrote:
> let's see if i got it right: the difference of REST design vs RPC
> (SOAP) is that in REST, the client states what the final state of the
> resource should be, and the server does whatever it needs to
> accomplish that. in RPC, the client initiates a process which can
> change states as it progresses.

Well, to be clear...
HTTP REST clients state what the final state of the resources should be,
and the server does whatever it needs to accomplish that. In RPC, the
client and server can do what they like. The REST difference is that the
request can be understood by arbitrary components in the network. This
includes intermediataries of various types, as well as more generic
clients like browsers that were not written for the sole purpose of
having this specific conversation.

> if this is true, what happens if the server can't reach the declared
> state? e.g., i have a printer, which i want to put online. i can
> POST/PUT 'online' to http://example.org/printers/pr1/status. but what
> if the actual process of making the physical printer fails? won't it
> be confusing if http://example.org/printers/pr1/status changes to
> 'error' by the server? it means the client can't be sure that what he
> posted stays. furthermore, once you allow both the server and client
> to modify resources, there's a risk of races. (or, maybe the part of
> the server that changes the resource can be thought of as a client?)

That is a server error. 500 is a good default, though if the reason for
the failure is known you could be more specific. 502 Bad Gateway, and
504 Gateway Timeout can be useful codes.

Benjamin.

On Tue, 2007-01-16 at 01:45 +0000, Duncan Cragg wrote:
> So - I promote a /symmetric/ REST point of view, with active
> resources 
> being dependent on each other and conveying state between themselves 
> with either GET or POST depending on which party initiates the
> transfer.
> 
> I do hope and believe this pattern is still REST-compatible. Please
> read 
> part 3 of my series 
> (http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/) 
> for more explanation of this pattern.
> 
> Of course, I probably end up thereby promoting POST idempotency, but
> I 
> see that as a good thing. Example: if you've added something to a
> list, 
> adding it again doesn't do anything. For some function
> same(resx,resy), 
> of course.

I think you are talking about making the POST idempotent by including a
unique identifier in the request content. If so, it sounds like an
application-specific form of idempotency. The server understands the
message, and when it goes to file it away it notices it already has a
matching record. This approach is often valid from the server side,
however the client is not in a particularly good position to predict
what whether its request will be processed multiple times.

I haven't read your content in detail as yet, but you also seem to be
including a pub/sub mechanism in your model. Again without knowing how
much of this you have covered exactly, subscription also has its
complications :)

> I break REST interaction down into three modes - from dumb to smart,
> via 
> dependent:
> -: If a resource receives such a direct transformation request or 
> intent, it may be *dumb* and go ahead and do just what it's told, 
> whenever it's told. That's what I was talking about in parts 1 and 2
> of 
> the dialogues. It's a bit like a database. I'd still do without PUT
> and 
> DELETE, mind, to prevent it being seen that way!

So, a flat file or equivalent that doesn't have any overlap with other
resources.

> -: Alternatively - what seems to be the subject of this thread - it
> may 
> have *real-world dependency*: maybe it can't just switch to 'running' 
> until the real world thing it models actually /is/ running! So, when
> it 
> receives a direct transformation intent, it goes off and satisfies
> that 
> constraint by ensuring it's ticking over in reality, and only then 
> changes its visible state to 'running'.

I'm a SCADA guy, so this is a kind of resource that comes frequently to
mind for me. This kind of resource can have knock-on effects also. If I
start a fan in a chiller plant for a building I am likely to see changes
to the resources demarcating temperature guage state. These changes slip
between resources via the implementation of these resources,
specifically the monitoring of changes to real world conditions.

> -: Finally, the resource may be *smart*, and decide to switch to 
> 'running' because of the rule that, as long as Joe's resource is 
> running, it should be running itself. So it spots Joe's resource 
> running, and starts running without even being told to! That's what I 
> was talking about in part 3 of my dialogues.

I suspect this is also the kind of resource that models most business
functions... though I would like to cut to the specifics. I see a set of
resources as an API to a service that expose its functionality in an
architecturally-consistent way. Importantly, they are not services in
their own right. They share state with each other, but this is not the
same as communicating with each other by RESTful means. They are
implemented with objects or with embedded database procedures. These
implementation-level entities talk to each other. That interaction is
what affects the service's resources.

So you have a service that is managing which other
services/devices/functions are running in its system. It observes a
change in one, and starts the other. The actual observation could be an
object notifying others via an observer pattern, it could be a process
starting or stopping and generating a SIGCHILD. It could be a resource
monitored via a configured or pub/sub notification mechanism or by GET
polling.

The systems I work with tend to have a lot of pub/sub relationships to
trigger knock-on behaviours between services. This is necessary because
changes to the real world are unpredictable to even the most aware
components in the architecture. Within a service we would typicically be
talking about the observer pattern. Between services and their cluster
management software we would be talking about the cluster keeping track
of which processes have started and not yet died.

Benjamin.

Benjamin Carlyle wrote:
> 
> 
> G'day,
> 
> I have been thinking about the idempotency of POST lately, and the
> exchange with Steve Bjorg has prompted me to write about it. My current
> direction is to treat a POST of null to a factory resource as
> idempotent.
> [...] 
> Thoughts?


Start here:

http://www.mnot.net/drafts/draft-nottingham-http-poe-00.txt
http://www.dehora.net/doc/httplr/draft-httplr-01.html

cheers
Bill

Taylor Parsons wrote:
> Why would you not use HTTPS?  As a user I would *never* enter my credit 
> card number that was not on HTTPS.  I am relatively new to use REST, is 
> there something that would prevent you from using HTTPS?
>  

One more time everyone:

THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN TRANSIT.

THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING VIEWED
IN THE BROWSER'S LOCATION BAR LOCALLY.

HTTPS DOES NOTHING TO SOLVE THIS.

Several people have suggested obscuring the card number, but
unfortunately the user still has to type it in, and there's no easy way
to change it.

I think a lot of folks are missing the point. There is a lot of data
that might go in a secret field but is not a password. Can we GET such data?


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

>  One more time everyone:
>
>  THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN TRANSIT.
>
>  THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING VIEWED
>  IN THE BROWSER'S LOCATION BAR LOCALLY.

In which case its got bugger all to do with http(s) transmission then.

No?

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Elliotte Harold wrote:
> One more time everyone:
> 
> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN TRANSIT.
> 
> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING VIEWED
> IN THE BROWSER'S LOCATION BAR LOCALLY.

The thing is, credit card numbers are not secrets. I mean, they're
printed on the front of the credit card in big readable digits.
-- 
Chris Burdess

Chris Burdess <dog@...> writes:

> Elliotte Harold wrote:
>> One more time everyone:
>> 
>> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN TRANSIT.
>> 
>> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING VIEWED
>> IN THE BROWSER'S LOCATION BAR LOCALLY.
>
> The thing is, credit card numbers are not secrets. I mean, they're
> printed on the front of the credit card in big readable digits.

And you give them to really high risk people every time you go into a
restaurant or petrol (that's "gas" to you) station.

Honestly, I know of a lot more fraud involving physical handing over
of the card than anything remotely clever like shoulder viewing or
electronic stealing.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Elliotte Harold <elharo@...> writes:

> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN TRANSIT.
>
> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING VIEWED
> IN THE BROWSER'S LOCATION BAR LOCALLY.
>
> HTTPS DOES NOTHING TO SOLVE THIS.
>
> Several people have suggested obscuring the card number, but
> unfortunately the user still has to type it in, and there's no easy way
> to change it.
>
> I think a lot of folks are missing the point. There is a lot of data
> that might go in a secret field but is not a password. Can we GET
> such data?

Yes. Users must (and mostly do, I think) understand the implications
of shoulder surfing.

They already understand them with ATMs.

Web application designers have to take on board some of the things
that ATM designers have taken on board (go look at an ATM and notice
all the measures they've taken to reduce shoulder surfing potential).

For example, if you put the credit card near the bottom of the screen
it's more difficult the read.

You can try this with someone standing behind you.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On 1/21/07, Nic James Ferrier <nferrier@...> wrote:
>  Yes. Users must (and mostly do, I think) understand the implications
>  of shoulder surfing.

Uh, I understand the general point of what you're saying, but, umm, if
you sat next to me and I put my creditcard into the URL, would you be
able to remember it? It's a long number. :) I guess one can say this
is security by obscurity, as someone might use their cameraphone and
snap a picture.

>  They already understand them with ATMs.

Well, actually they don't as you don't put in your credit-card number
in those machines. I'm even inclined to say that you could read your
number out loud to someone slowly, and they still wouldn't remember
it.

But back to the point, and here's what I would do to hide the
card-number in following transactions ;

   GET https://bank.com/card/1234567890

does a 30x redirect to ;

   https://bank.com/statement/$1234

which is a hashed version of whatever the card "1234567890" is linked
to (which could be a session indicator, a bank account, etc. depending
on how your internal system is designed).

If POSTing secret form data is the issue (as someone has pointed out),
I would connect the form to a hash of a login session, and pass the
hash in. So ;

   GET http://bank.com/login (returns form, with action to the URL below)

<form action="https://bank.com/session" method="post">
   Create a session<br />
   <input type="text" name="username" />
   <input type="secret" name="password" />
</form>

   POST https://bank.com/session (create session: returns 30x +
session hash $1234)

now you can use the hash to ;

   GET https://bank.com/statement/$1234

until ;

   DELETE https://bank.com/session/$1234 (or passed through by some form)


Alex
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

Chris Burdess wrote:

> The thing is, credit card numbers are not secrets. I mean, they're
> printed on the front of the credit card in big readable digits.

How about a social security number then? I think people are getting too 
wrapped up in the details and missing the forest for the trees.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Dave Pawson wrote:

> In which case its got bugger all to do with http(s) transmission then.
> 
> No?
> 

No. What it has to do with is the choice of GET vs. POST which is quite 
relevant to HTTP transmission.

The REST dogma is that safe operations should use get, where safe is 
defined as not changing server state or committing the user in any 
significant way. E.g. merely reading a page.

The question at hand is whether that dogma shoudl or shoudl not be 
modified to also take into account the sensitivity of the data in the 
query string that is exposed in the browser location bar, the bookmarks, 
the history, and other places.

The example of such data (and only an example) which I have offered is 
a credit card statement. Accessing the statement requires providing the 
credit card number, name on card, and so forth. This is sensitive 
information but the operation is not unsafe in the traditional sense. 
Merely reading one's statement is different than purchasing an item, 
which would be done with POST.

Is there a legitimate argument that this safe operation should 
nonetheless be performed with POST for reasons of security?

(If you don't like the credit card example, please feel free to 
substitute your own example of non-password sensitive data that should 
not be trivially exposed to prying eyes.)

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Elliotte Harold <elharo@...> writes:

> Chris Burdess wrote:
>
>> The thing is, credit card numbers are not secrets. I mean, they're
>> printed on the front of the credit card in big readable digits.
>
> How about a social security number then? I think people are getting too 
> wrapped up in the details and missing the forest for the trees.

Each case on it's merits. You asked about credit card numbers.

If we're talking about a range of differenct types of number then: I
wouldn't like to use a system that put my PIN number in a GET. But
any "username" (account numbers, id numbers, etc...) would be ok. It's
no different to the physical world.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Nic James Ferrier wrote:

> If we're talking about a range of differenct types of number then: I
> wouldn't like to use a system that put my PIN number in a GET. But
> any "username" (account numbers, id numbers, etc...) would be ok. It's
> no different to the physical world.
> 

A PIN or password can be sent with HTTP authentication. However many 
requests may involve more than just one confidential datum. The question 
remains:

Is it reasonable to use POST for a safe operation that transmits 
confidential data in the query string?

I can see arguments on both sides of the question. However, I'm a little 
surprised at the amount of effort I'm having to expend to get people to 
consider the question at all. The trouble people are going to evade it 
suggests to me that this is a very uncomfortable point for a lot of 
folks, and maybe the REST model (or at least HTTP) has some trouble here.

So far I think the two or three folks who've actually addressed the 
question square on have come down in favor of using POST despite the 
safety of the operation.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 1/21/07, Elliotte Harold <elharo@...> wrote:
> I can see arguments on both sides of the question. However, I'm a little
> surprised at the amount of effort I'm having to expend to get people to
> consider the question at all. The trouble people are going to evade it
> suggests to me that this is a very uncomfortable point for a lot of
> folks, and maybe the REST model (or at least HTTP) has some trouble here.

As I understand your question, you are purely concerned with shoulder-surfing.

If so, then your issue is technically with the browser rather than
RESTful architecture.

> So far I think the two or three folks who've actually addressed the
> question square on have come down in favor of using POST despite the
> safety of the operation.

There seems to be a general consensus across the thread that the
high-level solution is to encode the sensitive data string on the
querystring.

This this can be achieved in a number of ways:
1. POST the value(s) and the server redirects the browser to a URI
with the encoded value(s)
2. Encode the value(s) in the browser, either with local javascript or
via a an AJAX server call, and then update the html hrefs using the
DOM.

Don't forget the third alternative:
3. Redesign the web application to avoid the need to use sensitive
value(s) on a GET.

Regards, Alan Dean

Alan Dean wrote:

> There seems to be a general consensus across the thread that the
> high-level solution is to encode the sensitive data string on the
> querystring.

That's not generally possible, though. :-(

> This this can be achieved in a number of ways:
> 1. POST the value(s) and the server redirects the browser to a URI
> with the encoded value(s)

In which case you're using POST, which may indeed be the right answer; 
but I don't think it's RESTful.

> 2. Encode the value(s) in the browser, either with local javascript or
> via a an AJAX server call, and then update the html hrefs using the
> DOM.

Bleah. JavaScript cannot in general be relied on. If you have to rely on 
it, REST is already broken.

> Don't forget the third alternative:
> 3. Redesign the web application to avoid the need to use sensitive
> value(s) on a GET.

Easy enough to do, but then we're back to a non-RESTful POST where you 
should normally use GET. Maybe there are ways around this, but they're 
really jesuitical. For instance, you could only ask the user for their 
credit card info as part of an unsafe operation. Then you could assign 
them the unique ID that is not the credit card number for future use 
with GET. However, you would not allow the user to check their balance 
unless they'd done something else unsafe first. e.g. agreeing to a contract

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

>  > So far I think the two or three folks who've actually addressed the
>  > question square on have come down in favor of using POST despite the
>  > safety of the operation.
>
>  There seems to be a general consensus across the thread that the
>  high-level solution is to encode the sensitive data string on the
>  querystring.

That still avoids the question of whether it is wrong to use POST for
safe operations.

I still haven't see any principled (architectural/technical) argument
for that position.

Yes, you will lose some of the benefits of GET, but I assume you make
these choices with your eyes open, and don't care.

What does it hurt to use POST for a query?

On 1/21/07, Elliotte Harold <elharo@...> wrote:
> Alan Dean wrote:
>
> > There seems to be a general consensus across the thread that the
> > high-level solution is to encode the sensitive data string on the
> > querystring.
>
> That's not generally possible, though. :-(

Why do you assert it is not generally possible? I listed several means
to achieve it.

> > This this can be achieved in a number of ways:
> > 1. POST the value(s) and the server redirects the browser to a URI
> > with the encoded value(s)
>
> In which case you're using POST, which may indeed be the right answer;
> but I don't think it's RESTful.

POST is not antithetical to REST. POST has the fuzziest meaning, to be
sure, but is not without meaning. Why is a POST-initiated redirect not
RESTful? Furthermore, the target URI will be both RESTful and
encoded/obscured.

>
> > 2. Encode the value(s) in the browser, either with local javascript or
> > via a an AJAX server call, and then update the html hrefs using the
> > DOM.
>
> Bleah. JavaScript cannot in general be relied on. If you have to rely on
> it, REST is already broken.

Your conclusion does not follow on from the premise, I think.

> > Don't forget the third alternative:
> > 3. Redesign the web application to avoid the need to use sensitive
> > value(s) on a GET.
>
> Easy enough to do, but then we're back to a non-RESTful POST where you
> should normally use GET. Maybe there are ways around this, but they're
> really jesuitical. For instance, you could only ask the user for their
> credit card info as part of an unsafe operation. Then you could assign
> them the unique ID that is not the credit card number for future use
> with GET. However, you would not allow the user to check their balance
> unless they'd done something else unsafe first. e.g. agreeing to a contract

Perhaps you have misunderstood my point, which is that you could
design the URI 'representation space' without recourse to using the
credit card number at all. If you have authenticated the user (which
you have already acknowledged is out-of-scope to your question) then
the server can be aware of the credit card without propagating that
knowledge to the client (indeed, I would argue that to do so would be
bad security design).

Regards, Alan Dean

On 1/21/07, Bob Haugen <bob.haugen@...> wrote:
> > > So far I think the two or three folks who've actually addressed the
> > > question square on have come down in favor of using POST despite the
> > > safety of the operation.
> >
> > There seems to be a general consensus across the thread that the
> > high-level solution is to encode the sensitive data string on the
> > querystring.
>
> That still avoids the question of whether it is wrong to use POST for
> safe operations.

I specifically stated that I was answering the question of
shoulder-surfing the browser address bar.

>
> I still haven't see any principled (architectural/technical) argument
> for that position.
>
> Yes, you will lose some of the benefits of GET, but I assume you make
> these choices with your eyes open, and don't care.
>
> What does it hurt to use POST for a query?

Nothing in the HTTP spec prevents using POST as a safe operation. What
the spec prohibits is using GET/HEAD for *unsafe* operations.

"In particular, the convention has been established that the GET and
HEAD methods SHOULD NOT have the significance of taking an action
other than retrieval. These methods ought to be considered "safe".
This allows user agents to represent other methods, such as POST, PUT
and DELETE, in a special way, so that the user is made aware of the
fact that a possibly unsafe action is being requested."
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

Alan

Elliotte Harold <elharo@...> writes:

> I can see arguments on both sides of the question. However, I'm a little 
> surprised at the amount of effort I'm having to expend to get people to 
> consider the question at all. The trouble people are going to evade it 
> suggests to me that this is a very uncomfortable point for a lot of 
> folks, and maybe the REST model (or at least HTTP) has some trouble
> here.
>
> So far I think the two or three folks who've actually addressed the 
> question square on have come down in favor of using POST despite the 
> safety of the operation.

I don't think that's fair.

When you were talking about the use case of credit card numbers this
was a very familiar anti-pattern to me. Something that people suggest
is confidential actually, on analysis, turns out not to be.

I cannot think of a use case of the kind of thing that you're talking
about.

Some things are confidential. Indeed I wouldn't want someone to look
over my shoulder and notice the contents of many web pages that I look
at on a daily basis (bank account, visa account, telephone bills,
etc...)

But I don't see that any of that has anything to do with GET or
POST. What's in the URL bar is the least of my concerns.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Elliotte Harold wrote:

> I can see arguments on both sides of the question. However, I'm a little
> surprised at the amount of effort I'm having to expend to get people to
> consider the question at all. The trouble people are going to evade it
> suggests to me that this is a very uncomfortable point for a lot of
> folks, and maybe the REST model (or at least HTTP) has some trouble here.

Oh please, you sound like a witchfinder.  Provide a concrete example 
where you point would matter. If there's really a forest it can't be 
hard to see.

cheers
Bill

Elliotte's question is very valid, I think -- even if *you* don't  
have a problem with your credit card number being more or less public  
(I know I don't), protecting it is a typical user requirement. If you  
try to argue with a customer that what they want to see protected is  
not confidential at all, you've already lost the argument :-)

Still, I believe the "best" answer is that REST (or at least HTTP)  
relies on identifiers that are not secrets. If your identifiers are  
(or you consider them to be) secret, don't use them as URIs.

My personal favorite solution would be to create a new resource  
representing an application-specific "account" via posting the credit  
card number, and return a non-meaningful URI for that newly created  
(and reasonably protected) resource.

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/



On Jan 22, 2007, at 12:56 AM, Bill de hOra wrote:

> Elliotte Harold wrote:
>
> > I can see arguments on both sides of the question. However, I'm a  
> little
> > surprised at the amount of effort I'm having to expend to get  
> people to
> > consider the question at all. The trouble people are going to  
> evade it
> > suggests to me that this is a very uncomfortable point for a lot of
> > folks, and maybe the REST model (or at least HTTP) has some  
> trouble here.
>
> Oh please, you sound like a witchfinder. Provide a concrete example
> where you point would matter. If there's really a forest it can't be
> hard to see.
>
> cheers
> Bill

Bill de hOra wrote:
> Oh please, you sound like a witchfinder.

But a witchfinder that depends upon the witches using Craft names in 
public or public names in circle during a time of persecution instead of 
using an identifier appropriate to the context :)

The design flaw in 
http://example.net/doSomethingWith?id=sensitiveIdentifier isn't at the 
level of the application design that REST deals with.

 
> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN
TRANSIT.
>
> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING
VIEWED
> IN THE BROWSER'S LOCATION BAR LOCALLY.

Have the server do a redirect on the initial request.  This way you 
have the ability to perform a GET on the well-known URL, but it wouldn't

actually appear in the browser's address bar.

One more thing: The URL redirected to could be different on every
request of the original URL (encoded with using some random number and
could be made time-sensitive)

-----Original Message-----
From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
On Behalf Of Jeffrey Winter
Sent: Monday, January 22, 2007 9:06 AM
To: Elliotte Harold; REST Discuss
Subject: RE: [rest-discuss] Safe but secret


> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN
TRANSIT.
>
> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING
VIEWED
> IN THE BROWSER'S LOCATION BAR LOCALLY.

Have the server do a redirect on the initial request. This way you 
have the ability to perform a GET on the well-known URL, but it wouldn't

actually appear in the browser's address bar.

Jeffrey Winter wrote:
>  
>> THIS HAS NOTHING TO DO WITH THE CREDIT CARD NUMBER BEING SNIFFED IN
> TRANSIT.
>> THIS IS ABOUT THE CARD NUMBER (or other confidential data) BEING
> VIEWED
>> IN THE BROWSER'S LOCATION BAR LOCALLY.
> 
> Have the server do a redirect on the initial request.  This way you 
> have the ability to perform a GET on the well-known URL, but it wouldn't
> 
> actually appear in the browser's address bar.

Sometimes happens with redirects. Just use a safe identifier.

Stefan Tilkov wrote:
> Elliotte's question is very valid, I think 

yes; it's the conclusion re "evading" I have a problem with.

cheers
Bill

I'd like to publish some content in different formats. I think I'd like 
to use URLs as follows:

  http://example.com/docs/doc

for "the resource"; and atom, csv, rdf, zip:

  http://example.com/docs/doc/atom
  http://example.com/docs/doc/csv
  http://example.com/docs/doc/rdf

appended for "formats". Probably I'll use rel tags/URI templates and a 
howto page to document that you can get at representations in multiple 
forms.

I know there's conneg at the HTTP level, but it seems to have miserably, 
utterly, and completely failed* on the web.

Thoughts?

cheers
Bill

* http://www.xml.com/pub/a/2004/07/21/dive.html

>> Have the server do a redirect on the initial request. This way you 
>> have the ability to perform a GET on the well-known URL, but it
wouldn't
>> 
>> actually appear in the browser's address bar.
>
> Sometimes happens with redirects. Just use a safe identifier.

I'm not sure what you're getting at here.  It seems to me that
redirecting
from a GET of a "well-known" URL to a randomized, possibly
time-sensitive
URL addresses all the issues brought up in the original posting.

FWIW, this came over the transom today:

http://www.artima.com/weblogs/viewpost.jsp?thread=192218 

-----Original Message-----
From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
On Behalf Of Bill de hOra
Sent: Monday, January 22, 2007 10:20 AM
To: Rest List
Subject: [rest-discuss] using multiple urls for formats


I'd like to publish some content in different formats. I think I'd like 
to use URLs as follows:

http://example.com/docs/doc <http://example.com/docs/doc> 

for "the resource"; and atom, csv, rdf, zip:

http://example.com/docs/doc/atom <http://example.com/docs/doc/atom> 
http://example.com/docs/doc/csv <http://example.com/docs/doc/csv> 
http://example.com/docs/doc/rdf <http://example.com/docs/doc/rdf> 

appended for "formats". Probably I'll use rel tags/URI templates and a 
howto page to document that you can get at representations in multiple 
forms.

I know there's conneg at the HTTP level, but it seems to have miserably,

utterly, and completely failed* on the web.

Thoughts?

cheers
Bill

* http://www.xml.com/pub/a/2004/07/21/dive.html
<http://www.xml.com/pub/a/2004/07/21/dive.html> 


 

Quoting Bill de hOra <bill@...>:

> I'd like to publish some content in different formats. I think I'd like
> to use URLs as follows:
>
>   http://example.com/docs/doc
>
> for "the resource"; and atom, csv, rdf, zip:
>
>   http://example.com/docs/doc/atom
>   http://example.com/docs/doc/csv
>   http://example.com/docs/doc/rdf
>
> appended for "formats". Probably I'll use rel tags/URI templates and a
> howto page to document that you can get at representations in multiple
> forms.
>
> I know there's conneg at the HTTP level, but it seems to have miserably,
> utterly, and completely failed* on the web.
>
> Thoughts?

A lot of the time when people publish human and machine-readable  
formats, conneg doesn't seem appropriate, because the formats are  
really not substitutable for each other.  Eg, imagine the surprise  
that someone gets when they try to run XSLT over an XML representation  
but get a zip file because their XSLT processor isn't setting the  
Accept headers in exactly the way that the server expects.

I think that using multiple URLs is a good thing in that sort of  
scenario, but a weakness is that they become more difficult to manage.  
  Agents and languages like RDF can't easily tell whether two formats  
refer to the same concept.

A compromise is to additionally provide a URL for the concept, eg:  
"http://example.com/docs/doc", that 303-redirects to an appropriate  
representation, which also has the advantage of being compatible with  
the httpRange-14 resolution. [1]

Using the Link header [2] to point from the information resource (the  
file), to the non-information resource (the concept), seems like a  
good idea, but I'm not sure whether any of the predefined rel values  
are appropriate.

How about

Link: <http://example.com/docs/doc>; rev=alternate

(notice the rev instead of rel)


[1] http://lists.w3.org/Archives/Public/www-tag/2005Jun/0039.html
[2] http://www.apps.ietf.org/rfc/rfc2068.html#sec-19.6.2.4

-- 
Dave

Bill de hOra wrote:
> I'd like to publish some content in different formats. I think I'd like 
> to use URLs as follows:
> 
>   http://example.com/docs/doc
> 
> for "the resource"; and atom, csv, rdf, zip:
> 
>   http://example.com/docs/doc/atom
>   http://example.com/docs/doc/csv
>   http://example.com/docs/doc/rdf
> 
> appended for "formats". Probably I'll use rel tags/URI templates and a 
> howto page to document that you can get at representations in multiple 
> forms.

Why not use the idiomatic dot instead of slash here, Bill? e.g.,

    http://example.com/docs/doc.atom
    http://example.com/docs/doc.csv
    http://example.com/docs/doc.rdf

This has a couple of practical benefits:

    * `curl -O <URL>` (or Right Clicky -> Save As) does the Right
      Thing.

    * When you need to cache this stuff to disk, you can just use
      PATH_INFO directly. If you use the slash notation, you're
      "docs/doc" representation will collide with your "docs/doc"
      directory.

Am I missing something?

--
Ryan Tomayko
http://tomayko.com/

At Mon, 22 Jan 2007 15:20:14 +0000,
Bill de hOra <bill@...> wrote:
>
>
> I'd like to publish some content in different formats. I think I'd like
> to use URLs as follows:
>
>   http://example.com/docs/doc
>
> for "the resource"; and atom, csv, rdf, zip:
>
>   http://example.com/docs/doc/atom
>   http://example.com/docs/doc/csv
>   http://example.com/docs/doc/rdf
>
> appended for "formats". Probably I'll use rel tags/URI templates and a
> howto page to document that you can get at representations in multiple
> forms.

[…]

Hi Bill,

Is there something wrong with

  http://example.com/docs/doc

as the primary URL and:

  http://example.com/docs/doc.atom
  http://example.com/docs/doc.csv
  http://example.com/docs/doc.rdf

as the ones which ignore the Accept header, which would probably make
more sense to most users?

Also, I thought I’d just read a recommendation on how to do this, but
I can’t recall where. I’m trying to find it. IIRC, it suggests pretty
using the URLs as above with multiple formats served on the primary
URL based on the Accept header. It might have also involved 302s.

best,
Erik Hetzner

>
>Also, I thought I’d just read a recommendation on how to do this, but
>I can’t recall where. I’m trying to find it. IIRC, it suggests pretty
>using the URLs as above with multiple formats served on the primary
>URL based on the Accept header. It might have also involved 302s.
>

You may be thinking of this:

http://www.w3.org/2001/tag/doc/alternatives-discovery.html

-Eric

> * `curl -O <URL>` (or Right Clicky -> Save As) does the Right
> Thing.

Sold.

cheers
Bill

Erik Hetzner wrote:

> Hi Bill,
> 
> Is there something wrong with
> 
>   http://example.com/docs/doc
> 
> as the primary URL and:
> 
>   http://example.com/docs/doc.atom
>   http://example.com/docs/doc.csv
>   http://example.com/docs/doc.rdf
> 
> as the ones which ignore the Accept header, which would probably make
> more sense to most users?

Nope (and this is for Ryan too). I just happened to use a '/' instead of 
'.'. For no good reason, I blame Plone, which has been today's web 
system of choice.


> Also, I thought I’d just read a recommendation on how to do this, but
> I can’t recall where. I’m trying to find it. IIRC, it suggests pretty
> using the URLs as above with multiple formats served on the primary
> URL based on the Accept header. It might have also involved 302s.

I guess the issue here comes down to URI proliferation for a single 
resource. Mike Schinkel was asking about this recently; I think this is 
a case where a) multiple URIs one resource makes some kind of sense, b) 
it's becoming an idiomatic design pattern for web apps anyway. There is 
the accept/content-* machinery but no-one (statistically speaking) uses 
that stuff to obtain "the pdf" or whatever.

cheers
Bill

Hi,

I encountered a use case, which I want to get your opinion on.

Say that in my application I have a search form (resource that accepts search queries). Now, when someone clicks one of the results, I'd like to put into the page 'next' and 'prev' links (similar to what you have in bugzilla for example).

Now, one (bad) way of doing this, is keeping a state in the server that says the user is doing a search, and render the page with the links according to that state. This is bad because the user my get to the page in other ways (bookmarks, search something else and go back etc.), which will mean the 'back' and 'prev' links may be corrupted.

Another way is to make the links to the search results contain the fact that they originated from a search, with all search query data (maybe encoded in some way, e.g., serialized). 

This means two things: (a) the url to the resource contains data outside of the scope of the resource, (b) the returned representation contains information that is not part of the resource.

Is it OK to say that the search result contains urls which are not the resources themselves, but "meta resources" that wrap the real resource and add information?:
resource is http://example.org/resources/23
search is http://example.org/searches/43243otuou #  '43243otuou' is an encoding of the search parameters (instead of query string)
search result is: http://example.org/searces/43243otuou/1 # '1' says this is the first result
the latter returns something like:
  <next-result url="http://example.org/searces/43243otuou/2"/>
  <resource>
	# resource representation
  </resource>

also, when returning HTML, 'prev' and 'next' are embedded in the resource representation (somewhere between giving its name and other information). is it OK?

Thanks,
Ittay

-- 
===================================
Ittay Dror, 
Chief architect, 
R&D, Qlusters Inc.
ittayd@...
+972-3-6081994 Fax: +972-3-6081841

www.openqrm.org - Data Center Provisioning

[ Attachment content not displayed ]

[ Attachment content not displayed ]

On 1/22/07, Nikunj Mehta <nrmehtais@...> wrote:
>
> I was going through some mail archives and read that [1] PUT does not beget an ETag in the response. I quote from this reference below:
>
>
> > One problem is that the behavior of returning ETag in response to a PUT request isn't specified by HTTP
> >
>
> However a reading of 10.2.2 indicates otherwise. Since the reference I am quoting is rather recent, I am wondering what is missing? I would imagine that the ETag would be used with PUT in order to provide a desired level of concurrency control.
>
> I understand this is not an RFC 2616 discussion group, but this question is aimed at understanding how response headers are restricted by the operations requested of a resource.

I know it is rather chatty, but this is the way that interpret the
HTTP spec to obtain an ETag:

-->
PUT /foo

{entity}

<--
201 Created
Date: Mon, 22 Jan 2007 22:26:08 GMT

-->
HEAD /foo
If-Unmodified-Since: Mon, 22 Jan 2007 22:26:08 GMT

<--
200 OK
ETag: "abc123"

Hope that helps, Alan Dean

On 1/22/07, Nikunj Mehta <nrmehtais@...> wrote:
> I am trying to understand how strong entity tags are being generated for use with HTTP. Can anyone point to suitable resources or suggest options?

See my delicious links:

http://del.icio.us/alan.dean/etag

I use a hash of the entity for my etags.

Alan Dean

--- In rest-discuss@yahoogroups.com, "Alan Dean" <alan.dean@...> wrote:
>
> On 1/22/07, Nikunj Mehta <nrmehtais@...> wrote:
> >
> > I was going through some mail archives and read that [1] PUT does
not beget an ETag in the response. I quote from this reference below:
> >
> >
> > > One problem is that the behavior of returning ETag in response
to a PUT request isn't specified by HTTP
> > >
> I know it is rather chatty, but this is the way that interpret the
> HTTP spec to obtain an ETag:
> 
> -->
> PUT /foo
> 
> {entity}
> 
> <--
> 201 Created
> Date: Mon, 22 Jan 2007 22:26:08 GMT
> 
> -->
> HEAD /foo
> If-Unmodified-Since: Mon, 22 Jan 2007 22:26:08 GMT
> 
> <--
> 200 OK
> ETag: "abc123"
This is what I feared. Problem is that I lose track of the ETag at the
end of the first request. The RFC says that a server MAY do so. Do
most servers not return an ETag with the 201 Created response? If I am
writing a new server, would clients ignore the ETag returned for the
PUT response?

On 1/22/07, Ittay Dror <ittayd@...> wrote:
> Hi,
>
> I encountered a use case, which I want to get your opinion on.
>
> Say that in my application I have a search form (resource that accepts search queries). Now, when someone clicks one of the results, I'd like to put into the page 'next' and 'prev' links (similar to what you have in bugzilla for example).
>
> Now, one (bad) way of doing this, is keeping a state in the server that says the user is doing a search, and render the page with the links according to that state. This is bad because the user my get to the page in other ways (bookmarks, search something else and go back etc.), which will mean the 'back' and 'prev' links may be corrupted.
>
> Another way is to make the links to the search results contain the fact that they originated from a search, with all search query data (maybe encoded in some way, e.g., serialized).
>
> This means two things: (a) the url to the resource contains data outside of the scope of the resource, (b) the returned representation contains information that is not part of the resource.
>
> Is it OK to say that the search result contains urls which are not the resources themselves, but "meta resources" that wrap the real resource and add information?:

I'm having a hard time seeing why you would not just use either of the
following for a simple term search, such as 'rest':

http://example.com?q=rest  ... google style
or
http://example.com/search/rest ... delicious style

for pagination:

http://example.com?q=rest&page=1
or
http://example.com/search/rest/page/1
or
http://example.com/search/rest?page=1

Alan Dean

On 1/22/07, nrmehta <nrmehtais@...> wrote:
> This is what I feared. Problem is that I lose track of the ETag at the
> end of the first request. The RFC says that a server MAY do so. Do
> most servers not return an ETag with the 201 Created response? If I am
> writing a new server, would clients ignore the ETag returned for the
> PUT response?


Yeah, I've been around this particular house too ;-)

As it happens, I write in .net and the runtime sinks ETag headers if
they are set because a 201 response is not cacheable.

As to the clients, I haven't the foggiest - browsers don't support PUT
and pretty much all the other clients are hand-cranked / proprietory.
I'm guessing that any MS software will ignore it on a PUT (just a
guess from the server-side .net behaviour).

Maybe someone who works in Java / Perl / PHP can advise what the
default behaviour is in those runtimes.

I have to admit it seems odd to send an ETag along with a response
marked no-cache, but it is permitted by the spec if you wish to do so.


Alan Dean

Bill de hOra wrote:
> 
> 
> Erik Hetzner wrote:
>  
>  > Also, I thought I’d just read a recommendation on how to do this, but
>  > I can’t recall where. I’m trying to find it. IIRC, it suggests pretty
>  > using the URLs as above with multiple formats served on the primary
>  > URL based on the Accept header. It might have also involved 302s.
> 
> I guess the issue here comes down to URI proliferation for a single
> resource. Mike Schinkel was asking about this recently; I think this is
> a case where a) multiple URIs one resource makes some kind of sense, b)
> it's becoming an idiomatic design pattern for web apps anyway. There is
> the accept/content-* machinery but no-one (statistically speaking) uses
> that stuff to obtain "the pdf" or whatever.

"print this page" falls under the idiom as well. Any usability people on 
the list?

cheers
Bill

At Mon, 22 Jan 2007 20:59:56 +0000,
Bill de hOra wrote:
> I guess the issue here comes down to URI proliferation for a single
> resource. Mike Schinkel was asking about this recently; I think this is
> a case where a) multiple URIs one resource makes some kind of sense, b)
> it's becoming an idiomatic design pattern for web apps anyway. There is
> the accept/content-* machinery but no-one (statistically speaking) uses
> that stuff to obtain "the pdf" or whatever.

I like content negotiation, in theory & for applications, but if I
know that <http://example.org/doc> has a pdf representation & I can’t
get it in my browser by appending ‘.pdf’ I’m going to be frustrated.

And URI proliferation doesn’t seem to be that bad. From
<http://www.w3.org/2001/tag/doc/alternatives-discovery.html#id2262384>

> Principal Conclusions:
>
> * URIs are cheap. Create them as needed, publish them to the Web,
> and ensure that they are appropriately linked in to the rest of the
> Web. Thus, each representation of interest should get it’s own URI
> (become a specific resource) and there should be one additional URI
> representing the generic resource.

best,
Erik Hetzner

On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
> As it happens, I write in .net and the runtime sinks ETag headers if
> they are set because a 201 response is not cacheable.

That's dumb.  Which version of the runtime?

...
> I have to admit it seems odd to send an ETag along with a response
> marked no-cache, but it is permitted by the spec if you wish to do so.

ETag is not an entity-header. ETag provides information about the
resource, not the current message, so it is orthogonal to cache
control.

....Roy

Hi Roy,

On Jan 22, 2007, at 3:59 PM, Roy T. Fielding wrote:

> On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
>> I have to admit it seems odd to send an ETag along with a response
>> marked no-cache, but it is permitted by the spec if you wish to do  
>> so.
>
> ETag is not an entity-header. ETag provides information about the
> resource, not the current message, so it is orthogonal to cache
> control.
>
Hmm. How else might an ETag be used other than determining if a  
cached entity is still current?

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On Jan 22, 2007, at 4:11 PM, Bill Venners wrote:

> Hi Roy,
>
> On Jan 22, 2007, at 3:59 PM, Roy T. Fielding wrote:
>
>> On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
>>> I have to admit it seems odd to send an ETag along with a response
>>> marked no-cache, but it is permitted by the spec if you wish to  
>>> do so.
>>
>> ETag is not an entity-header. ETag provides information about the
>> resource, not the current message, so it is orthogonal to cache
>> control.
>>
> Hmm. How else might an ETag be used other than determining if a  
> cached entity is still current?

The ETag *header field* is a response header.  The entity-tag value
contained within that header field may be used in *later* requests
for cache-related conditionals, like If-None-Match and If-Match.

The entity tag is actually metadata about the internal resource
mapping on the server -- it does not necessarily reflect anything
about the content (other than the premise that the value must
change whenever the content is changed).  That is why it doesn't
matter which status code is used or what content is supplied in
the response message, since the Etag is referring to the mapping
operation rather than the content of *this* message.  Hence, the
ETag provided in a 201 response must be the entity-tag of the
mapping result after completing the resource-changing operation.

It is a tricky thing to understand, and the spec does a poor job
of explaining it.

....Roy

On Mon, 22 Jan 2007, Bill de hOra wrote:

 > I'd like to publish some content in different formats. I think I'd like 
 > to use URLs as follows:
 > 
 >   http://example.com/docs/doc
 > 
 > for "the resource"; and atom, csv, rdf, zip:
 > 
 >   http://example.com/docs/doc/atom
 >   http://example.com/docs/doc/csv
 >   http://example.com/docs/doc/rdf

I agree with most other people: If you're not going to use content
negotiation and you expect people not computers to be using these URLs,
use doc.atom, doc.csv, etc.

 > appended for "formats". Probably I'll use rel tags/URI templates and a 
 > howto page to document that you can get at representations in multiple 
 > forms.

Can you elaborate on this a bit or point me to a resource that does? I
assume you mean that the HTML representation will inlude <link>s to
alternate stuff? I wish browsers exposed that stuff a bit more.

 > I know there's conneg at the HTTP level, but it seems to have miserably, 
 > utterly, and completely failed* on the web.

It's failed on the people web, but seems to work pretty well for little
client to little (or big) servers. AJAX requests for JSON
representations and the like, command line tools that pull editable
representations to vim, whatever.

When we built the Socialtext REST (sic?) API [1] we debated for quite a
while about content-negotation. Initially I wanted the "user's web front
end" to use the same URLs as "api's front end" and figured something
like what you describe would be useful. Compromise eventually settled us
on an api front end that gets used by the interface and we declared
(very simple) content negotation the way to go, as code was always
going to be there to set the Accept header.

This of course turned out to be only sort of true. Code is written by
people who like to go exploring with their browsers. Library code is
sometimes written by people who don't know about the Accept header.

So now there is an ?accept=<type> parameter accepted by most
representations. I wonder if it would also be useful to implement
.<filetype extension>?


[1]
https://www.socialtext.net/st-rest-docs/index.cgi?socialtext_rest_documentation
-- 
Chris Dent                      http://burningchrome.com/~cdent/mt
                              [...]

[ Attachment content not displayed ]

On Jan 22, 2007, at 4:34 PM, Roy T. Fielding wrote:

> On Jan 22, 2007, at 4:11 PM, Bill Venners wrote:
>
>> Hi Roy,
>>
>> On Jan 22, 2007, at 3:59 PM, Roy T. Fielding wrote:
>>
>>> On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
>>>> I have to admit it seems odd to send an ETag along with a response
>>>> marked no-cache, but it is permitted by the spec if you wish to  
>>>> do so.
>>>
>>> ETag is not an entity-header. ETag provides information about the
>>> resource, not the current message, so it is orthogonal to cache
>>> control.
>>>
>> Hmm. How else might an ETag be used other than determining if a  
>> cached entity is still current?
>
> The ETag *header field* is a response header.  The entity-tag value
> contained within that header field may be used in *later* requests
> for cache-related conditionals, like If-None-Match and If-Match.
>
> The entity tag is actually metadata about the internal resource
> mapping on the server -- it does not necessarily reflect anything
> about the content (other than the premise that the value must
> change whenever the content is changed).  That is why it doesn't
> matter which status code is used or what content is supplied in
> the response message, since the Etag is referring to the mapping
> operation rather than the content of *this* message.  Hence, the
> ETag provided in a 201 response must be the entity-tag of the
> mapping result after completing the resource-changing operation.
>
> It is a tricky thing to understand, and the spec does a poor job
> of explaining it.
>
I think you clarified it. I believe I understand your point about 201  
after PUT, but could you clarify what you mean by "internal resource  
mapping?" Do you mean the way a server will map a URI to a  
representation? But if content negotiation is taking place, the  
server would need the request headers too to determine a  
representation, not just a URI. What does "internal resource mapping"  
mean? What's being mapped to what?

Thanks.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

Ittay Dror wrote:
> Say that in my application I have a search form (resource that accepts search queries). Now, when someone clicks one of the results, I'd like to put into the page 'next' and 'prev' links (similar to what you have in bugzilla for example).
> 
> Now, one (bad) way of doing this, is keeping a state in the server that says the user is doing a search, and render the page with the links according to that state. This is bad because the user my get to the page in other ways (bookmarks, search something else and go back etc.), which will mean the 'back' and 'prev' links may be corrupted.
> 
> Another way is to make the links to the search results contain the fact that they originated from a search, with all search query data (maybe encoded in some way, e.g., serialized). 

Yes. The latter is the correct way, at least if you want this system to
scale. There's no need to encode the query data (aprt from URL
encoding), just specify it as query parameters.

> This means two things: (a) the url to the resource contains data outside of the scope of the resource, (b) the returned representation contains information that is not part of the resource.

Not really, no. When you say "resource", you seem to be implying that
there is a one-to-one mapping between resources and results. However,
within this system you're designing a resource also contains information
about the context it was located in, so it's not the same as a result.
The resource is simply the thing that is pointed to by the URL,
including all this query context data.

> Is it OK to say that the search result contains urls which are not the resources themselves, but "meta resources" that wrap the real resource and add information?:

Not quite, see above. The search result will return both context data
and results. These can be combined to form URLs that reference resources
that combine both the context data and the result.

> also, when returning HTML, 'prev' and 'next' are embedded in the resource representation (somewhere between giving its name and other information). is it OK?

Yes.
-- 
Chris Burdess

On 1/22/07, Roy T. Fielding <fielding@...> wrote:
> On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
> > As it happens, I write in .net and the runtime sinks ETag headers if
> > they are set because a 201 response is not cacheable.
>
> That's dumb.  Which version of the runtime?
[snip]
> ETag is not an entity-header. ETag provides information about the
> resource, not the current message, so it is orthogonal to cache
> control.
>
> ....Roy

I just did a double-check to make sure that I'm not talking out of my
hat, and yes - the ETag is sunk if Cache-Control is set to no-cache.

I'm using frameowrk v2.0 - don't know what the behaviour of previous
versions is.

Alan Dean

On 1/23/07, Roy T. Fielding <fielding@...> wrote:
> The ETag *header field* is a response header.  The entity-tag value
> contained within that header field may be used in *later* requests
> for cache-related conditionals, like If-None-Match and If-Match.
>
> The entity tag is actually metadata about the internal resource
> mapping on the server -- it does not necessarily reflect anything
> about the content (other than the premise that the value must
> change whenever the content is changed).  That is why it doesn't
> matter which status code is used or what content is supplied in
> the response message, since the Etag is referring to the mapping
> operation rather than the content of *this* message.  Hence, the
> ETag provided in a 201 response must be the entity-tag of the
> mapping result after completing the resource-changing operation.
>
> It is a tricky thing to understand, and the spec does a poor job
> of explaining it.
>
> ....Roy

Following the logic that ETag should be provided with a 201 Created,
should one be provided with a 304 Not Modified too?

What about empty ETags?

204 No Content
ETag: ""

or:

404 Not Found
ETag: ""

Alan Dean

Alan Dean schrieb:
> 
> 
> On 1/23/07, Roy T. Fielding <fielding@gbiv. com 
> <mailto:fielding%40gbiv.com>> wrote:
>  > The ETag *header field* is a response header. The entity-tag value
>  > contained within that header field may be used in *later* requests
>  > for cache-related conditionals, like If-None-Match and If-Match.
>  >
>  > The entity tag is actually metadata about the internal resource
>  > mapping on the server -- it does not necessarily reflect anything
>  > about the content (other than the premise that the value must
>  > change whenever the content is changed). That is why it doesn't
>  > matter which status code is used or what content is supplied in
>  > the response message, since the Etag is referring to the mapping
>  > operation rather than the content of *this* message. Hence, the
>  > ETag provided in a 201 response must be the entity-tag of the
>  > mapping result after completing the resource-changing operation.
>  >
>  > It is a tricky thing to understand, and the spec does a poor job
>  > of explaining it.
>  >
>  > ....Roy
> 
> Following the logic that ETag should be provided with a 201 Created,
> should one be provided with a 304 Not Modified too?

Yes. <http://greenbytes.de/tech/webdav/rfc2616.html#status.304>:

"The response MUST include the following header fields:

     * Date, unless its omission is required by Section 14.18.1

If a clockless origin server obeys these rules, and proxies and clients 
add their own Date to any response received without one (as already 
specified by [RFC 2068], section 14.19), caches will operate correctly.

     * ETag and/or Content-Location, if the header would have been sent 
in a 200 response to the same request
     * Expires, Cache-Control, and/or Vary, if the field-value might 
differ from that sent in any previous response for the same variant"

> What about empty ETags?
> 
> 204 No Content
> ETag: ""
> 
> or:
> 
> 404 Not Found
> ETag: ""

In this case it's not empty, but consists of two characters. That being 
said, I think it's legal but I really wouldn't be surprised if some 
recipients have trouble handling it.

Anyway; it seems to me that a better place for this discussion would be 
the HTTP working group's mailing list. In particular, because the topic 
of ETags upon PUT has been discussed over there as well.

Best regards, Julian

Hi,

Something I've been pondering the last few days is basically if there
is a preference to POST new items as ;

   GET http://example.com/items/1234 , returns 404
   POST http://example.com/items/1234
   (there is no list concept; only resources)

or

   GET http://example.com/items/1234 , returns 404
   POST http://example.com/items with 1234 as parameter value ,
returns above URL
   (/items is the concept of a list which you post new items to, or
work with a list)

I can see the first option being nice in terms of PUT and DELETE as
well, but some times you are in situations where you don't know the
/1234 identifier upfront (for session hashes, for example)

Any thoughts on the list? Is the mix of the two perhaps a better way, as in ;

   POST / GET http://example.com/item/1234 , returns 404 (note no plural)
   POST / GET http://example.com/items (plural for 'list' operations)


Regards,

Alexander
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

Hi Alexander,

my take on this: if you want to tell your clients what resource is a collection they can POST to, use Atom Publishing Protocol <service> documents[1].

HTH,

Jan
[1] http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-12.txt


 
On Tuesday, January 23, 2007, at 12:21PM, "Alexander Johannesen" <alexander.johannesen@...> wrote:
>Hi,
>
>Something I've been pondering the last few days is basically if there
>is a preference to POST new items as ;
>
>   GET http://example.com/items/1234 , returns 404
>   POST http://example.com/items/1234
>   (there is no list concept; only resources)
>
>or
>
>   GET http://example.com/items/1234 , returns 404
>   POST http://example.com/items with 1234 as parameter value ,
>returns above URL
>   (/items is the concept of a list which you post new items to, or
>work with a list)
>
>I can see the first option being nice in terms of PUT and DELETE as
>well, but some times you are in situations where you don't know the
>/1234 identifier upfront (for session hashes, for example)
>
>Any thoughts on the list? Is the mix of the two perhaps a better way, as in ;
>
>   POST / GET http://example.com/item/1234 , returns 404 (note no plural)
>   POST / GET http://example.com/items (plural for 'list' operations)
>
>
>Regards,
>
>Alexander
>-- 
> ---------------------------------------------------------------------------
> Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
>------------------------------------------ http://shelter.nu/blog/ --------
>
>
> 
>Yahoo! Groups Links
>
>
>
>
>

Alexander Johannesen wrote:
>    GET http://example.com/items/1234 , returns 404
>    POST http://example.com/items/1234
>    (there is no list concept; only resources)

That makes little sense if http://example.com/items/1234 doesn't 
identify a resource (hence 404) then it doesn't identify a resource so 
only PUT makes sense (or DELETE to maintain its idempotency - two 
DELETEs should work).

If http://example.com/items/1234 does identify a resource, but you can't 
GET it, then it should return 405.

>    GET http://example.com/items/1234 , returns 404
>    POST http://example.com/items with 1234 as parameter value ,
> returns above URL
>    (/items is the concept of a list which you post new items to, or
> work with a list)
> 
> I can see the first option being nice in terms of PUT and DELETE as
> well, but some times you are in situations where you don't know the
> /1234 identifier upfront (for session hashes, for example)

Agreed. Not having the parameter value, but having the 1234 determined 
by the server and then the client informed by the 303 response works well.

> Any thoughts on the list? Is the mix of the two perhaps a better way, as in ;
> 
>    POST / GET http://example.com/item/1234 , returns 404 (note no plural)
>    POST / GET http://example.com/items (plural for 'list' operations)

Either is RESTful, since no particular relationship between 
http://example.com/item/1234 and http://example.com/item is entailed. 
However it can certainly be guessed at, so it seems better URI design to 
have one "up the path" from the other, though using the plural in both 
cases may make more sense http://example.com/items identifies the items 
and http://example.com/items/1234 identifies that one of the items 
numbered 1234.

On 1/23/07, Julian Reschke <julian.reschke@...> wrote:
> In this case it's not empty, but consists of two characters. That being
> said, I think it's legal but I really wouldn't be surprised if some
> recipients have trouble handling it.

I was under the impression that all ETag values were quoted, and so an
empty ETag in the form "" was the correct ETag for a missing resource.
Can't recall were I picked this idea up from, but there you are. This
interpretation allows you to specify that an action should only be
carried out if the resource is missing, e.g.

-->
PUT /foo
If-Match: ""

Regards, Alan Dean

On 1/23/07, Jan Algermissen <algermissen1971@...> wrote:
> my take on this: if you want to tell your clients what resource is a collection
> they can POST to, use Atom Publishing Protocol <service> documents[1].

I've tried to wrap my head around APP, but can't seem to do it,
possibly from the lack of examples. The standard itself uses a lot of
abstract speak without actual examples of normal transactions using
APP. Unless you've got some good pointers to examples I'm not sure I
can rely on it just quite yet, it's a bit fresh and unproven in my
eyes although I'm certainly interested and hear good things about it.


Regards,

Alex
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

On 1/23/07, Jon Hanna <jon@...> wrote:

> Agreed. Not having the parameter value, but having the 1234 determined
> by the server and then the client informed by the 303 response works well.

I was entailing a POST to /items would create a 201 ('created') with
an ETag of either the redirect URL or the resource identifier
(although none feels "best" to me). If I do a 303 on the /items URL
then that's saying the /items resource has moved permanently
elsewhere?

>  Either is RESTful, since no particular relationship between
>  http://example.com/item/1234 and http://example.com/item is entailed.
>  However it can certainly be guessed at, so it seems better URI design to
>  have one "up the path" from the other, though using the plural in both
>  cases may make more sense http://example.com/items identifies the items
>  and http://example.com/items/1234 identifies that one of the items
>  numbered 1234.

Agreed, and I'm probably heading that way. The reason this question
came up was that applications might be trying to GET a /items/1234 to
check if a session resource is still available with 404 for not
created, 410 for lost/timed-out, or 200 if it's still there. If a 410
is given, they could POST to the same URL again to put it back (200).
I guess a POST is ok for 410 but not for 404 in this case. Hmm, maybe
I should try to avoid that, and just allow another POST to the /items
URL and use the session hash (1234) as a parameter to override the
creation of a new and instead use the one I know about. Thoughts?


Alex
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

Alan Dean schrieb:
> 
> 
> On 1/23/07, Julian Reschke <julian.reschke@ gmx.de 
> <mailto:julian.reschke%40gmx.de>> wrote:
>  > In this case it's not empty, but consists of two characters. That being
>  > said, I think it's legal but I really wouldn't be surprised if some
>  > recipients have trouble handling it.
> 
> I was under the impression that all ETag values were quoted, and so an
> empty ETag in the form "" was the correct ETag for a missing resource.
> Can't recall were I picked this idea up from, but there you are. This
> interpretation allows you to specify that an action should only be
> carried out if the resource is missing, e.g.
> 
> -->
> PUT /foo
> If-Match: ""

Nope.

But you could use

	If-None-Match: "*"

(see <http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.26.p.2>)

Best regards, Julian

Alexander Johannesen wrote:
> On 1/23/07, Jon Hanna <jon@...> wrote:
> 
>> Agreed. Not having the parameter value, but having the 1234 determined
>> by the server and then the client informed by the 303 response works well.
> 
> I was entailing a POST to /items would create a 201 ('created') with
> an ETag of either the redirect URL or the resource identifier
> (although none feels "best" to me). If I do a 303 on the /items URL
> then that's saying the /items resource has moved permanently
> elsewhere?

201 is grand but I'm unsure as to whether existing UAs then move to that 
resource or not. 303 doesn't imply /items has moved, 303 is "See Other" 
and means that the POST to /items has done something and the URI in the 
header shows where something relating to what was done is GETtable.

> I guess a POST is ok for 410 but not for 404 in this case. Hmm, maybe
> I should try to avoid that, and just allow another POST to the /items
> URL and use the session hash (1234) as a parameter to override the
> creation of a new and instead use the one I know about. Thoughts?

POST acts on a resource. 410 indicates the resource is gone. How can you 
act on something that has gone?

It'll probably work, but it smells bad to me.

Hi Taylor,

On Jan 22, 2007, at 6:41 PM, Taylor Parsons wrote:

> REST url format for returning serialized data in formats other then  
> default.
>
> For example does any feel strongly about either of these two formats?

David Hansson certainly does. :-)  The former is now the default in  
Rails 1.2.

http://weblog.rubyonrails.org/2007/1/19/rails-1-2-rest-admiration- 
http-lovefest-and-utf-8-celebrations

That may not mean he's "right", but I tend to trust his instincts.   
Plus, Rails is (I think) the first major web app framework to  
wholeheartedly switch to a RESTful approach, so I think it provides a  
useful precedent.

That said, I can imagine cases where the latter would feel more  
natural or easy to code; but if you're unsure, I'd go with the former  
(and Rails).

-enp

>
> First approach parse the file file format as the switch for decide  
> how the caller wants the data formatted.
>  /baseURL/method/doc.rss
>  /baseURL/method/doc.json
>  /baseURL/method/doc.xml
>  /baseURL/method/doc.html
>
> Second approach the default return format would be html, and we add  
> in a feeds sub-dir and a file format to use as our switch.
>  /baseURL/feeds/rss/method/
>  /baseURL/feeds/json/method/
>  /baseURL/feeds/xml/method/

A great piece of writing on the topic by Sean McGrath:

http://www.itworld.com/Tech/2327/nlsebiz070123/pfindex.html

Entertaining too!


Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

With all of the discussions about the handling of ETags, If-Match, etc 
I thought that I would put up the flowchart we are using to define our 
test cases.

See http://www.flickr.com/photos/alan-dean/367132415/

If you notice any errors or misunderstanding of the HTTP spec in the 
diagram, please let me know :-)

Regards,
Alan Dean

Bill de hOra wrote:
> 
> 
> Erik Hetzner wrote:
> 
>  > Hi Bill,
>  >
>  > Is there something wrong with
>  >
>  > http://example.com/docs/doc <http://example.com/docs/doc>
>  >
>  > as the primary URL and:
>  >
>  > http://example.com/docs/doc.atom <http://example.com/docs/doc.atom>
>  > http://example.com/docs/doc.csv <http://example.com/docs/doc.csv>
>  > http://example.com/docs/doc.rdf <http://example.com/docs/doc.rdf>
>  >
>  > as the ones which ignore the Accept header, which would probably make
>  > more sense to most users?
> 
> Nope (and this is for Ryan too). I just happened to use a '/' instead of
> '.'. For no good reason, I blame Plone, which has been today's web
> system of choice.

As an aside; it seems you can't do this (append an extension) in Plone, 
or more properly Zope2,  because of the way object traversal there works 
with the URI path. You can do this instead:

   http://example.com/docs/doc/entry.atom

oh well.

cheers
Bill

David Powell wrote:

> A lot of the time when people publish human and machine-readable  
> formats, conneg doesn't seem appropriate, because the formats are  
> really not substitutable for each other.  Eg, imagine the surprise  
> that someone gets when they try to run XSLT over an XML representation  
> but get a zip file because their XSLT processor isn't setting the  
> Accept headers in exactly the way that the server expects.

That's a really serious bug in the XSLT processor then. Any XSLT 
processor that says it prefers to get zipped files, and then doesn't 
handle them; well that's almost (but not quite) too dumb to be believed.

If such a thing exists, it's only because servers aren't respecting 
conneg. Fail fast is a feature, not a bug. Working around broken 
software is an antipattern we have to do away with.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 1/22/07, Roy T. Fielding <fielding@...> wrote:
> On Jan 22, 2007, at 2:59 PM, Alan Dean wrote:
> > As it happens, I write in .net and the runtime sinks ETag headers if
> > they are set because a 201 response is not cacheable.
>
> That's dumb.  Which version of the runtime?
>
> ...
> > I have to admit it seems odd to send an ETag along with a response
> > marked no-cache, but it is permitted by the spec if you wish to do so.
>
> ETag is not an entity-header. ETag provides information about the
> resource, not the current message, so it is orthogonal to cache
> control.
>
> ....Roy
>

For information:

I have raised this issue with MS support - this is the feedback:

"I received your mail yesterday. I understand you want to tell me that
our products should follow RFC document. But unfortunately, in most
cases, we take these documents as a reference instead of following it
completely. Anyway, I agree with you that Cache-Control tag is not
directly related to ETag.

I've discuss the issue with a senior engineer in our team. According
to the discussion, we decide to feedback your issue to our product
team. However, the request may takes a long time for the product team
to handle as they have to decide if there is any side effect for this
modification. Furthermore, I can't determine whether they will fix it
or not. In any stage of the process of the fix request, the product
team may have authority to reject this request. This is completely out
of my control. Sorry for that.

I'll keep you update about the latest status of the request. Your
patience will be greatly appreciated!"

So, at least they acknowledge the issue (although with no promise to fix).

Alan Dean

On 1/24/07, Alan Dean <alan.dean@...> wrote:
>  See http://www.flickr.com/photos/alan-dean/367132415/

Thanks for that; a fantastic resource. I've been using it the last few
days to implement a simple REST utility for our internal SOA, and this
was just what I needed.

Is there a REST FAQ / Wiki somewhere where this chart is mandatory?


Alex
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

On 1/25/07, Alexander Johannesen <alexander.johannesen@...> wrote:
> On 1/24/07, Alan Dean <alan.dean@...> wrote:
> >  See http://www.flickr.com/photos/alan-dean/367132415/
>
> Thanks for that; a fantastic resource. I've been using it the last few
> days to implement a simple REST utility for our internal SOA, and this
> was just what I needed.
>
> Is there a REST FAQ / Wiki somewhere where this chart is mandatory?

This was put together by me directly from the HTTP spec, it wasn't
taken from an FAQ or Wiki but I am not asserting any restrictions on
use so if there is a FAQ or Wiki that wants to republish it - feel
free

:-)

Alan Dean

On 1/25/07, Alan Dean <alan.dean@...> wrote:
> ... I am not asserting any restrictions on use so if there is a FAQ or Wiki that wants to republish it - feel free

Of course, it would be nice if I was quoted as creator :-)

Alan Dean schrieb:
> 
> 
> With all of the discussions about the handling of ETags, If-Match, etc
> I thought that I would put up the flowchart we are using to define our
> test cases.
> 
> See http://www.flickr. com/photos/ alan-dean/ 367132415/ 
> <http://www.flickr.com/photos/alan-dean/367132415/>
> 
> If you notice any errors or misunderstanding of the HTTP spec in the
> diagram, please let me know :-)
> 
> Regards,
> Alan Dean

I think one thing that is missing is a more generic handling of method 
names (you may have that somewhere else in your code, but it's missing 
from the diagram).

For instance, MKCOL to an unmapped URI should either succeed (201) or 
fail with 405 (method not allowed).

Best regards, Julian

On 1/25/07, Julian Reschke <julian.reschke@...> wrote:
>
> I think one thing that is missing is a more generic handling of method
> names (you may have that somewhere else in your code, but it's missing
> from the diagram).
>
> For instance, MKCOL to an unmapped URI should either succeed (201) or
> fail with 405 (method not allowed).
>
> Best regards, Julian
>

Yes - I was only trying to model the RFC2616 HTTP 1.1 Spec, not WebDAV.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

Regards, Alan

Alan Dean schrieb:
> On 1/25/07, Julian Reschke <julian.reschke@...> wrote:
>>
>> I think one thing that is missing is a more generic handling of method
>> names (you may have that somewhere else in your code, but it's missing
>> from the diagram).
>>
>> For instance, MKCOL to an unmapped URI should either succeed (201) or
>> fail with 405 (method not allowed).
>>
>> Best regards, Julian
>>
> 
> Yes - I was only trying to model the RFC2616 HTTP 1.1 Spec, not WebDAV.
> 
> http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

...but that still requires returning the right status code when you 
don't know the method name, right?

Best regards, Julian

On 1/25/07, Julian Reschke <julian.reschke@...> wrote:
>
> ...but that still requires returning the right status code when you
> don't know the method name, right?

If the file / entity exists and the verb is not in (PUT, POST, DELETE,
GET, HEAD) then the flow dictates that a 405 Method Not Allowed is
returned.

Actually in my code, the method names are whitelisted and the 405 is
returned for any method name not on the whitelist (which, in my case,
would include MKCOL).

To be honest the flow described by the diagram is focused on the
resolution of the various headers, rather than the methods allowed.

Maybe there is a poential project for someone interested in WebDAV to
do the same kind of thing including other methods - not me though ;-)

Regards, Alan

Alan Dean schrieb:
> 
> 
> On 1/25/07, Julian Reschke <julian.reschke@ gmx.de 
> <mailto:julian.reschke%40gmx.de>> wrote:
>  >
>  > ...but that still requires returning the right status code when you
>  > don't know the method name, right?
> 
> If the file / entity exists and the verb is not in (PUT, POST, DELETE,
> GET, HEAD) then the flow dictates that a 405 Method Not Allowed is
> returned.
> 
> Actually in my code, the method names are whitelisted and the 405 is
> returned for any method name not on the whitelist (which, in my case,
> would include MKCOL).
> 
> To be honest the flow described by the diagram is focused on the
> resolution of the various headers, rather than the methods allowed.
> 
> Maybe there is a poential project for someone interested in WebDAV to
> do the same kind of thing including other methods - not me though ;-)

Understood.

I just wanted to clarify that the flow graph is not complete with 
respect to this (as unsupported methods to an unmapped resource would 
return 404, not 405).

Best regards, Julian

On Sun, 2007-01-21 at 11:57 -0500, Elliotte Harold wrote:
> Is it reasonable to use POST for a safe operation that transmits 
> confidential data in the query string?

No, it is not reasonable. You lose your caching potential, which is one
thing... but the main practical thing is that the browser will need a
button every time it navigates from one page to another. Surely you
won't just have one page with the secret credit card as part of the url.
There are bound to be dozens of urls that contain that information if
only to look through historical records. Using POST with currently
technology limits your ability to use simple recognisable hyperlinks.

On a pure architectural level secrets don't really matter too much. You
can do what you want with them. If they are secret they aren't known by
many people and are less likely to be frequently fetched than other
kinds of data. They don't beneifit as much as other resources from
caching and other architectural niceties.

On the other hand, I hold POST to mean "append the data I provide" which
is clearly not what is meant in this case. Using methods inconsistently
is recipe for mismatch and confusion everywhere.

So... no. Don't use POST. It will cause you headaches, and is not
necessary at all.

> So far I think the two or three folks who've actually addressed the 
> question square on have come down in favor of using POST despite the 
> safety of the operation.

I think you have missed the discussion about safe hashes for secret
data. If the data is secret it isn't just shoulder surfing you have to
worry about. Using that secret data in an identifier anywhere in your
application is a no no. Even if you trust your employees, you have a
duty of care to keep what your customers consider secrets secret as much
as possible. You should have a table that maps this secret data to a
non-secret hash. An examples:

Credit card to non-secret hash table
1234 4567 78 -> 001
4567 1234 90 -> 002

Now instead of visiting <http://example.com/12345678> your user visits
<http://example.com/001>, which is the URL you told him to visit. You
might have done this by sending him the URL in the mail. You might have
done it by asking him to fill in a form with his credit card number in
it that returned or redirected to this url. You might have simply
hyperlinked to this url from the user's personalised main page.

The point is that whenever you put secret data in identifiers you
guarantee that everyone in the company will be able to access the
information. Don't do that. Use a hash instead. Then you at least have
some hope of being able to expose the secrets to as small a subset of
your employee community as possible. Naturally, this also solves the
shoulder surfing problem... so long as the user doesn't type their
credit card number in to that form while someone is watching.

Benjamin.

On Tue, 2007-01-23 at 23:16 +1100, Alexander Johannesen wrote:
> On 1/23/07, Jon Hanna <jon@...> wrote:
> > Either is RESTful, since no particular relationship between
> > http://example.com/item/1234 and http://example.com/item is
> entailed.
> > However it can certainly be guessed at, so it seems better URI
> design to
> > have one "up the path" from the other, though using the plural in
> both
> > cases may make more sense http://example.com/items identifies the
> items
> > and http://example.com/items/1234 identifies that one of the items
> > numbered 1234.
> Agreed, and I'm probably heading that way. The reason this question
> came up was that applications might be trying to GET a /items/1234 to
> check if a session resource is still available with 404 for not
> created, 410 for lost/timed-out, or 200 if it's still there. If a 410
> is given, they could POST to the same URL again to put it back (200).

Use POST for resource creation through http://example.com/items that you
expect to return a new url as determined by the server. Use PUT for
resource creation to http://example.com/items/1234 where you expect the
server to honour the client-provided url and create the resource
in-place. See rfc2616. POST to a factory resource such as
http://example.com/items is often preferred because it allows the server
greater freedom to shuffle you off somewhere else based on it's current
world view.

> I guess a POST is ok for 410 but not for 404 in this case. Hmm, maybe
> I should try to avoid that, and just allow another POST to the /items
> URL and use the session hash (1234) as a parameter to override the
> creation of a new and instead use the one I know about. Thoughts?

I think you are talking about renewing session state...
<shrug> I personally would think about doing this as a side-effect of
the GET request. GET is a safe method, meaning the server can't swear in
court later that the client actually wanted to renew their session, but
the server is free to revoke the session at any time if it wants to
anyway. It is just noticing that the session is still in use and making
an internal decision to keep it active.

On the other hand, you should perhaps be thinking about what this
session is for. REST tends to discourage sessions in general. Without
looking at your specific use case I wouldn't like to comment too
harshly, but a session can often be avoided.

Benjamin

On 1/26/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> I think you are talking about renewing session state...
> <shrug> I personally would think about doing this as a side-effect of
> the GET request. GET is a safe method, meaning the server can't swear in
> court later that the client actually wanted to renew their session, but
> the server is free to revoke the session at any time if it wants to
> anyway. It is just noticing that the session is still in use and making
> an internal decision to keep it active.

I am dealing with sessions in this case, but I'm making them RESTful
by treating them as resources, and that brings up the interesting
point of temporary resources. What happens when you GET a temporary
resource that's expired, but you can get back through invocation? A
410 means its gone, 404 means it's not found, 304 not modified, and so
forth; there seems to be nothing that says "yes, it's still there, but
you need to ask pretty to get it back".

Currently I'm just going to let the sessions exsist until asked to be
removed, and have the timeout information inside the XML of the GET
operation and let applications decide if they're "allowed" to use the
info within, as I can't seem to find a RESTful mechanism to use.

> On the other hand, you should perhaps be thinking about what this
> session is for. REST tends to discourage sessions in general. Without
> looking at your specific use case I wouldn't like to comment too
> harshly, but a session can often be avoided.

These session objects can be created by anyone, from browsers to
applications to services, and is a temporary property store with
timestamps. They are anonymous, and there is no dependancy on
application logic, so it's up to the apps to use them properly, for
example a browser needs to get a session, use it with cookies, and
check the timeout from time to time, or a cron service uses the
session for various cleaning jobs, etc.

Never mind that they are sessions. think of them as temporary
resources that after a time become unavailable (but not gone), and you
can ask to get them back.


Alex
-- 
 ---------------------------------------------------------------------------
 Project Wrangler, SOA, Information Alchymist, UX, RESTafarian, Topic Maps
------------------------------------------ http://shelter.nu/blog/ --------

Alan: nice work! Is there a higher resolution version of:

   http://farm1.static.flickr.com/175/367132415_ee9c3b9b40_b_d.jpg

available?

//Ed

Alexander Johannesen wrote:

> These session objects can be created by anyone, from browsers to
> applications to services, and is a temporary property store with
> timestamps. They are anonymous, and there is no dependancy on
> application logic, so it's up to the apps to use them properly, for
> example a browser needs to get a session, use it with cookies, and
> check the timeout from time to time, or a cron service uses the
> session for various cleaning jobs, etc.
> 
> Never mind that they are sessions. think of them as temporary
> resources that after a time become unavailable (but not gone), and you
> can ask to get them back.

In my mind once sessions are finished they're finished for good. not 
turned off. I think you're dealing with two types of resource - one is a 
session (transient), another is (maybe) the state of a client.

cheers
Bill

On Sat, 2007-01-20 at 19:57 +0000, Bill de hOra wrote:
> Benjamin Carlyle wrote:
> > I have been thinking about the idempotency of POST lately, and the
> > exchange with Steve Bjorg has prompted me to write about it. My
> current
> > direction is to treat a POST of null to a factory resource as
> > idempotent.
> > [...] 
> > Thoughts?
> Start here:
> http://www.mnot.net/drafts/draft-nottingham-http-poe-00.txt
> http://www.dehora.net/doc/httplr/draft-httplr-01.html

Thanks for the links.

Problems with POE:
* The specification does not cover how the POE resource is created.
Presumably, it is through a POST which could lead to a chicken and egg
situation. My proposal to POST null is designed to create the temporary
resource from a factory with a stable url, solving this problem.
* POST is consumed on the POE resource, and can't be used for other
normal purposes. For example, I can't use this mechanism to create a
factory resource. OTOH, the POST null approach only deals with creation
of the resource. POST is available for normal uses on the created
resource.

On HTTPLR:
* This seems fairly similar to the POST null proposal. In fact, step one
of the upload protocol appears to be a null POST with step two being the
PUT. I'm not sure about the explicit client DELETE of the channel, and
thus I'm not sure about the need for the channel concept at all. A
server must be free to time out the new resource in case of premature
client failure, so you can't guarantee delivery unless the request
sequence completes before this timeout. In light of this I prefer the
channel concept to simply be replaced by the concept of a created
resource.
* I think there is some danger that the message could be read to be a
whole HTTP request or SOAP request or other request that needs to be
delivered. That interpretation doesn't smell right to me, and I think
that any suggestion of message transfer should be explicitly avoided in
favour of state transfer.
* The GET appears OK, though clearly the server must also be free to
purge old messages once its buffers start to fill up. This is a matter
of summarisation that also affects pub/sub mechanisms.

I think my suggestion remains intact and I'll look to implementing it
where at most once delivery is required in my architecture. The current
factory resource pattern where a new resource is created by POSTing its
state to the factory is replaced by a two-phase operation. Phase one is
the same POST but with no content:
>> POST http://example.com/resourcefactory
<< 201 Created
<< Location: http://example.com/theresource
Phase two is to PUT the content you would have otherwise POSTed:
>> PUT http://example.com/theresource
>> <<the resource state>>
<< 200 OK
Either step can be repeated safely so long as the client doesn't
backtrack by dong a POST after a PUT has been sent and so long as the
server doesn't time out the created resource before the client is sure
the creation has occured. If 200 is returned from the POST a reliable
delivery is not possible and a regular POST should be attempted. To
support a reliable POST the server must create a temporary resource from
the POST.

Benjamin.

On 27.01.2007, at 06:32, Benjamin Carlyle wrote:

>
> Problems with POE:
> * The specification does not cover how the POE resource is created.
> Presumably, it is through a POST which could lead to a chicken and egg
> situation.

Yes to both.

I had another thought the other day:

The model I am thinking about to achieve POE is based on the use of  
Atom and the inclusion of an ID in the POST body (or an HTTP header).  
POE aware clients would receive the ID to use from a factory, non-POE  
aware clients would just do the normal POST.

The problem with getting the IDs is of course that it violates GET's  
idempotency (every GET will result in a new ID). OTH, IDs are cheap  
and if we are not talking about hundreds of GETs per second to the  
factory, it is propably not that bad at all. It is after all just a  
resource changing over time.

Another thought I had was that the client could probably create the  
ID itself (e.g. a tag: URI) and a new HTTP return code could indicate  
to the client that the ID was't suitable (together with a good one in  
the payload).

Thoughts?

Jan



> My proposal to POST null is designed to create the temporary
> resource from a factory with a stable url, solving this problem.
> * POST is consumed on the POE resource, and can't be used for other
> normal purposes. For example, I can't use this mechanism to create a
> factory resource. OTOH, the POST null approach only deals with  
> creation
> of the resource. POST is available for normal uses on the created
> resource.
>
> On HTTPLR:
> * This seems fairly similar to the POST null proposal. In fact,  
> step one
> of the upload protocol appears to be a null POST with step two  
> being the
> PUT. I'm not sure about the explicit client DELETE of the channel, and
> thus I'm not sure about the need for the channel concept at all. A
> server must be free to time out the new resource in case of premature
> client failure, so you can't guarantee delivery unless the request
> sequence completes before this timeout. In light of this I prefer the
> channel concept to simply be replaced by the concept of a created
> resource.
> * I think there is some danger that the message could be read to be a
> whole HTTP request or SOAP request or other request that needs to be
> delivered. That interpretation doesn't smell right to me, and I think
> that any suggestion of message transfer should be explicitly  
> avoided in
> favour of state transfer.
> * The GET appears OK, though clearly the server must also be free to
> purge old messages once its buffers start to fill up. This is a matter
> of summarisation that also affects pub/sub mechanisms.
>
> I think my suggestion remains intact and I'll look to implementing it
> where at most once delivery is required in my architecture. The  
> current
> factory resource pattern where a new resource is created by POSTing  
> its
> state to the factory is replaced by a two-phase operation. Phase  
> one is
> the same POST but with no content:
>>> POST http://example.com/resourcefactory
> << 201 Created
> << Location: http://example.com/theresource
> Phase two is to PUT the content you would have otherwise POSTed:
>>> PUT http://example.com/theresource
>>> <<the resource state>>
> << 200 OK
> Either step can be repeated safely so long as the client doesn't
> backtrack by dong a POST after a PUT has been sent and so long as the
> server doesn't time out the created resource before the client is sure
> the creation has occured. If 200 is returned from the POST a reliable
> delivery is not possible and a regular POST should be attempted. To
> support a reliable POST the server must create a temporary resource  
> from
> the POST.
>
> Benjamin.
>
>
>
>
> Yahoo! Groups Links
>
>
>

On 27.01.2007, at 11:32, Jan Algermissen wrote:

>
> I had another thought the other day:

Well, to be fair,  credits for this actually go to Phil:
http://www.imc.org/atom-protocol/mail-archive/msg08072.html

Jan

>
> The model I am thinking about to achieve POE is based on the use of
> Atom and the inclusion of an ID in the POST body (or an HTTP header).
> POE aware clients would receive the ID to use from a factory, non-POE
> aware clients would just do the normal POST.
>
> The problem with getting the IDs is of course that it violates GET's
> idempotency (every GET will result in a new ID). OTH, IDs are cheap
> and if we are not talking about hundreds of GETs per second to the
> factory, it is propably not that bad at all. It is after all just a
> resource changing over time.
>
> Another thought I had was that the client could probably create the
> ID itself (e.g. a tag: URI) and a new HTTP return code could indicate
> to the client that the ID was't suitable (together with a good one in
> the payload).
>
> Thoughts?
>
> Jan
>
>
>
>> My proposal to POST null is designed to create the temporary
>> resource from a factory with a stable url, solving this problem.
>> * POST is consumed on the POE resource, and can't be used for other
>> normal purposes. For example, I can't use this mechanism to create a
>> factory resource. OTOH, the POST null approach only deals with
>> creation
>> of the resource. POST is available for normal uses on the created
>> resource.
>>
>> On HTTPLR:
>> * This seems fairly similar to the POST null proposal. In fact,
>> step one
>> of the upload protocol appears to be a null POST with step two
>> being the
>> PUT. I'm not sure about the explicit client DELETE of the channel,  
>> and
>> thus I'm not sure about the need for the channel concept at all. A
>> server must be free to time out the new resource in case of premature
>> client failure, so you can't guarantee delivery unless the request
>> sequence completes before this timeout. In light of this I prefer the
>> channel concept to simply be replaced by the concept of a created
>> resource.
>> * I think there is some danger that the message could be read to be a
>> whole HTTP request or SOAP request or other request that needs to be
>> delivered. That interpretation doesn't smell right to me, and I think
>> that any suggestion of message transfer should be explicitly
>> avoided in
>> favour of state transfer.
>> * The GET appears OK, though clearly the server must also be free to
>> purge old messages once its buffers start to fill up. This is a  
>> matter
>> of summarisation that also affects pub/sub mechanisms.
>>
>> I think my suggestion remains intact and I'll look to implementing it
>> where at most once delivery is required in my architecture. The
>> current
>> factory resource pattern where a new resource is created by POSTing
>> its
>> state to the factory is replaced by a two-phase operation. Phase
>> one is
>> the same POST but with no content:
>>>> POST http://example.com/resourcefactory
>> << 201 Created
>> << Location: http://example.com/theresource
>> Phase two is to PUT the content you would have otherwise POSTed:
>>>> PUT http://example.com/theresource
>>>> <<the resource state>>
>> << 200 OK
>> Either step can be repeated safely so long as the client doesn't
>> backtrack by dong a POST after a PUT has been sent and so long as the
>> server doesn't time out the created resource before the client is  
>> sure
>> the creation has occured. If 200 is returned from the POST a reliable
>> delivery is not possible and a regular POST should be attempted. To
>> support a reliable POST the server must create a temporary resource
>> from
>> the POST.
>>
>> Benjamin.
>>
>>
>>
>>
>> Yahoo! Groups Links
>>
>>
>>
>
>
>
>
> Yahoo! Groups Links
>
>
>

On 1/27/07, Jan Algermissen <algermissen1971@...> wrote:
>
> The problem with getting the IDs is of course that it violates GET's
> idempotency (every GET will result in a new ID). OTH, IDs are cheap
> and if we are not talking about hundreds of GETs per second to the
> factory, it is propably not that bad at all. It is after all just a
> resource changing over time.
>

Breaking the idempotency of GET is very bad ...

Why not have a 'factory' GET, that redirects to a new location every time, e.g.

-->
GET /id/new

<--
302 Found
Location: /id/abc123

-->
GET /id/new

<--
302 Found
Location: /id/abc124

... etc

Regards, Alan Dean

On 27.01.2007, at 11:49, Alan Dean wrote:

> On 1/27/07, Jan Algermissen <algermissen1971@...> wrote:
>>
>> The problem with getting the IDs is of course that it violates GET's
>> idempotency (every GET will result in a new ID). OTH, IDs are cheap
>> and if we are not talking about hundreds of GETs per second to the
>> factory, it is propably not that bad at all. It is after all just a
>> resource changing over time.
>>
>
> Breaking the idempotency of GET is very bad ...

Yes, but a) it is the server's responsibility and b) it is very  
controlled in this case.

(Is there any harm in those HTML pages that show N-times visited  
numbers? The foo.org/collection/latestPOEId resource would just  
behave the same way.

>
> Why not have a 'factory' GET, that redirects to a new location  
> every time, e.g.

But the side effect would still be there.

Jan

>
> -->
> GET /id/new
>
> <--
> 302 Found
> Location: /id/abc123
>
> -->
> GET /id/new
>
> <--
> 302 Found
> Location: /id/abc124
>
> ... etc
>
> Regards, Alan Dean

Jan Algermissen wrote:

> The problem with getting the IDs is of course that it violates GET's 
> idempotency (every GET will result in a new ID). OTH, IDs are cheap and 
> if we are not talking about hundreds of GETs per second to the factory, 
> it is propably not that bad at all. It is after all just a resource 
> changing over time


The problem in my mind GET a cached ID and sharing it with someone else. 
If you want to serve IDs have clients use POST.

cheers
Bill

Benjamin Carlyle wrote:
> 
> On HTTPLR:
> * This seems fairly similar to the POST null proposal. In fact, step one
> of the upload protocol appears to be a null POST with step two being the
> PUT. I'm not sure about the explicit client DELETE of the channel, and
> thus I'm not sure about the need for the channel concept at all. A
> server must be free to time out the new resource in case of premature
> client failure, so you can't guarantee delivery unless the request
> sequence completes before this timeout. 

Perhaps. You could guarantee delivery by having the client restart the 
exchange if the server indicates a timeout (or generally ending the 
exchange). It's another confused client scenario. IME, the operational 
scenario are exchanges that are started but a client will never finish 
(phantoms), which is why I documented them.


In light of this I prefer the
> channel concept to simply be replaced by the concept of a created
> resource.

Maybe. Where you're worried about the reality of timeouts, I'm worried 
about the reality of HTTPLR acting as a gateway for MOMs.


> * I think there is some danger that the message could be read to be a
> whole HTTP request or SOAP request or other request that needs to be
> delivered. That interpretation doesn't smell right to me, and I think
> that any suggestion of message transfer should be explicitly avoided in
> favour of state transfer.

Again, maybe. Did you see any testable/operational consequences?


> * The GET appears OK, though clearly the server must also be free to
> purge old messages once its buffers start to fill up. This is a matter
> of summarisation that also affects pub/sub mechanisms.
> 
> I think my suggestion remains intact and I'll look to implementing it
> where at most once delivery is required in my architecture. 

Fair enough; at most isn't the same guaranteed. I had thought once about 
clients and serves being able to negitiate the SLA, but profile 
negotiation in internet protocols never seems to work out just so.

cheers
Bill

On Jan 27, 2007, at 7:13 AM, Bill de hOra wrote:

> Jan Algermissen wrote:
>
>> The problem with getting the IDs is of course that it violates GET's
>> idempotency (every GET will result in a new ID). OTH, IDs are  
>> cheap and
>> if we are not talking about hundreds of GETs per second to the  
>> factory,
>> it is propably not that bad at all. It is after all just a resource
>> changing over time
>
>
> The problem in my mind GET a cached ID and sharing it with someone  
> else.
> If you want to serve IDs have clients use POST.
>
Where does it say that GET is idempotent? My understanding was that  
GET is "safe," but not necessarily idempotent. Returning a new ID  
each time you do a GET seems plenty safe to me. People used to do  
that all the time when they put a "This page has been views N time"  
counters on their pages. And can't you simply put a cache-control  
header that says don't cache and must revalidate to prevent people  
getting duplicate IDs? If someone backs up with the back button on a  
browser, they might attempt the same ID twice, but I believe  
detecting that is the point of the proposal--i.e., to prevent the  
same thing from being posted twice.

Bill
----
Bill Venners
President
Artima, Inc.
http://www.artima.com

On 1/27/07, Bill Venners <bv-svp@...> wrote:
>
> Where does it say that GET is idempotent?

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.2

"9.1.2 Idempotent Methods

Methods can also have the property of "idempotence" in that (aside
from error or expiration issues) the side-effects of N > 0 identical
requests is the same as for a single request. The methods GET, HEAD,
PUT and DELETE share this property. Also, the methods OPTIONS and
TRACE SHOULD NOT have side effects, and so are inherently idempotent."

Alan Dean

Bill Venners wrote:
> 
> On Jan 27, 2007, at 7:13 AM, Bill de hOra wrote:
> 
>> Jan Algermissen wrote:
>>
>>> The problem with getting the IDs is of course that it violates GET's
>>> idempotency (every GET will result in a new ID). OTH, IDs are cheap and
>>> if we are not talking about hundreds of GETs per second to the factory,
>>> it is propably not that bad at all. It is after all just a resource
>>> changing over time
>>
>>
>> The problem in my mind GET a cached ID and sharing it with someone else.
>> If you want to serve IDs have clients use POST.
>>
> Where does it say that GET is idempotent? My understanding was that GET 
> is "safe," but not necessarily idempotent. Returning a new ID each time 
> you do a GET seems plenty safe to me. 

Hi Bill,

It's not that. The safeness of GET can work against you, if the server 
is required to issue distinct ids.

client A

  GET -------[cache] -------> [oserver]

  200 Ok
  id:23098765678

client B

  GET -------[cache] x

  200 Ok
  id:23098765678


client B was served from cache, so now client A and B are working with 
the same ID. Not good. Hence, use POST for this kind of pattern, unless 
you have some other means of distinguishing A and B requests.


cheers
Bill

Bill,

On 27.01.2007, at 16:13, Bill de hOra wrote:

> Jan Algermissen wrote:
>
>> The problem with getting the IDs is of course that it violates GET's
>> idempotency (every GET will result in a new ID). OTH, IDs are  
>> cheap and
>> if we are not talking about hundreds of GETs per second to the  
>> factory,
>> it is propably not that bad at all. It is after all just a resource
>> changing over time
>
>
> The problem in my mind GET a cached ID and sharing it with someone  
> else.
>

Yes, that might be a problem (an ill-behaving cache should not  
confuse other peoples POSTs).


> If you want to serve IDs have clients use POST.

Yes, but then we have the chicken-egg problem that Benjamin  
mentioned. If one wants to do reliable POST, then using simple POST  
to get the IDs is probably a bit brain dead, eh?

OTH, if the client understands what the extra-capability of support  
for POEs means (and obviously it has to do so) then part of that  
understanding could be that myriads of retried normal POSTs to the  
factory are ok by definition.

What I don't see yet is whether this 'overwriting' of HTTP semantics  
is ok or bad or architecturally deadly.

I recall that WAKA might introduce 'Request Identifiers', is that  
something that could be used here? Would such identifiers be  
generated by the client and would re-POSTs use the same identifier?

Or maybe letting the client supply the ID for the POST (and have the  
server complain if the ID is bad) is indeed the right thing to do,  
thoughts?

Thanks,

Jan

>
> cheers
> Bill
>
>
>
>
>
>
>
>
>
>
>
>
>
> Yahoo! Groups Links
>
>
>

On 2007/01/27, at 4:32 PM, Benjamin Carlyle wrote:

> On Sat, 2007-01-20 at 19:57 +0000, Bill de hOra wrote:
>> Benjamin Carlyle wrote:
>>> I have been thinking about the idempotency of POST lately, and the
>>> exchange with Steve Bjorg has prompted me to write about it. My
>> current
>>> direction is to treat a POST of null to a factory resource as
>>> idempotent.
>>> [...]
>>> Thoughts?
>> Start here:
>> http://www.mnot.net/drafts/draft-nottingham-http-poe-00.txt
>> http://www.dehora.net/doc/httplr/draft-httplr-01.html
>
> Thanks for the links.
>
> Problems with POE:
> * The specification does not cover how the POE resource is created.

That's intentional :)

> Presumably, it is through a POST which could lead to a chicken and egg
> situation.

Sending a POST to get the form is one way, but not the only.

Another would be to use GET, and assure that the response isn't  
cacheable; there are a number of ways to assure that the links you've  
given out don't collide without keeping a list of them, the easiest  
involving timestamps (along with some other information) or GUIDs.

Yet another would be to delegate creating the links to the client,  
e.g., using JavaScript.

I don't see how sending a POST to get the POE link leads to a chicken- 
and-egg problem, unless you also need the "get the form" operation  
(which really should be a GET) to be reliable as well. Even if you  
did, you can always bootstrap it with one that isn't required to be  
reliable.

> * POST is consumed on the POE resource, and can't be used for other  
> normal purposes. For example, I can't use this mechanism to create  
> a factory resource.

201 Created + Location.

Cheers,

P.S. I'm happy to update/improve upon POE if people think it's worth  
walking down that path.


--
Mark Nottingham     http://www.mnot.net/

On 1/25/07, Edward Summers <ehs@...> wrote:
> Alan: nice work! Is there a higher resolution version of:
>
> http://farm1.static.flickr.com/175/367132415_ee9c3b9b40_b_d.jpg
>
> available?

Yes. I don't know why, but flickr lowered the resolution of the uploaded file.

I will upload a full-res copy over the weekend to my site and publish
the URL here.

Alan

On 1/25/07, Edward Summers <ehs@...> wrote:
> Alan: nice work! Is there a higher resolution version of:
>
> http://farm1.static.flickr.com/175/367132415_ee9c3b9b40_b_d.jpg
>
> available?

A full-res jpg can be found at

http://thoughtpad.net/who/alan-dean/image/http-headers-status.jpg

Regards, Alan Dean

On 1/28/07, Dave Pawson <dave.pawson@...> wrote:
> >  Yes. I don't know why, but flickr lowered the resolution of the uploaded file.
> >
> >  I will upload a full-res copy over the weekend to my site and publish
> >  the URL here.
>
> <greedy>An SVG format would make it even more useful Alan</greedy>
>
> I'm wondering if flickr is hurting of storage space, hence don't like
> large files?

The diagram was edited in Visio. I will check tomorrow to see if it
can export in SVG format.

Regards,
Alan Dean

Jan Algermissen wrote:
> 
> 
> Bill,
>
>  > If you want to serve IDs have clients use POST.
> 
> Yes, but then we have the chicken-egg problem that Benjamin
> mentioned. If one wants to do reliable POST, then using simple POST
> to get the IDs is probably a bit brain dead, eh?

Not brain dead, it will work, as the point is you don't need a reliable 
single POST to start  a reliable exchange - reliability is introduced 
using a sequence of requests and key for communicating shared state 
(HTTP is an asymmetric protocol, so it isn't possible to this in one 
step anyway). If you request an ID and fail to get a response, then 
request again. The main thing is that the ID is not shared with other 
clients. Without that the server can't reason correctly about exchange 
state.


> What I don't see yet is whether this 'overwriting' of HTTP semantics
> is ok or bad or architecturally deadly.
> 
> I recall that WAKA might introduce 'Request Identifiers', is that
> something that could be used here? Would such identifiers be
> generated by the client and would re-POSTs use the same identifier?

HTTPLR uses URLs to identify the message exchange (that is, the ids are 
URLs). That's for management reasons - you want to be able to 
distinguish between the exchange state and what's being exchanged.

cheers
Bill

Mark Nottingham wrote:

> I don't see how sending a POST to get the POE link leads to a 
> chicken-and-egg problem, unless you also need the "get the form" 
> operation (which really should be a GET) to be reliable as well. Even if 
> you did, you can always bootstrap it with one that isn't required to be 
> reliable.

I agree. I think POE is sound, formally speaking.

The chicken and egg problem I've see is that, because HTTP is asymmetric 
(clients always initiate), then it's possible that either the client or 
the server gets confused as to where things are at because the client 
never got the response, or never got the response in time. I assumed 
that out of HTTPLR by saying infinite requests will result in infinite 
responses. Protocol axioms are wonderful that way ;)

cheers
Bill

On 28.01.2007, at 19:18, Bill de hOra wrote:

> If you request an ID and fail to get a response, then
> request again.

Well, ok. But this behavior is only appropriate if suggested as part  
of the spec. It contradicts HTTP in the sense that you as a client  
should know that there might be side effects, so re-POSTing is  
somewhat dangerous. It is the special character of the POE factory  
that the re-POSTing side effect is of no concern.

Thanks,

Jan

Jan Algermissen wrote:
> 
> On 28.01.2007, at 19:18, Bill de hOra wrote:
> 
>> If you request an ID and fail to get a response, then 
>>
>> request again.
>>
> 
> Well, ok. But this behavior is only appropriate if suggested as part of 
> the spec. It contradicts HTTP in the sense that you as a client should 
> know that there might be side effects, so re-POSTing is somewhat 
> dangerous. It is the special character of the POE factory that the 
> re-POSTing side effect is of no concern.

I see what you're saying. But if the client doesn't get a response, or 
gets a non-2xx response what should it do, according to HTTP?

cheers
Bill

On 28.01.2007, at 21:17, Bill de hOra wrote:

> I see what you're saying. But if the client doesn't get a response, or
> gets a non-2xx response what should it do, according to HTTP?

At least not go into "Brute Force Retry Mode" :-)
But I guess in this case it is ok. For my part, I'll follow the POST- 
to-POE-collection-factory road. Thanks for all the comments - this  
thing is trickier than it first appears.

Jan

On 1/28/07, Dave Pawson <dave.pawson@...> wrote:
>
> <greedy>An SVG format would make it even more useful Alan</greedy>

An svg version now available at

http://thoughtpad.net/who/alan-dean/image/http-headers-status.svg

as well as the original

http://thoughtpad.net/who/alan-dean/image/http-headers-status.jpg

Regards,
Alan Dean

On 29/01/07, Alan Dean <alan.dean@...> wrote:
> An svg version now available at
>
> http://thoughtpad.net/who/alan-dean/image/http-headers-status.svg

Views great in Batik. Pan and zoom without loss of clarity!

Thanks Alan.
Very useful.

regards



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Alan Dean wrote:
> 
> 
> On 1/28/07, Dave Pawson <dave.pawson@... 
> <mailto:dave.pawson%40gmail.com>> wrote:
>  >
>  > <greedy>An SVG format would make it even more useful Alan</greedy>
> 
> An svg version now available at
> 
> http://thoughtpad.net/who/alan-dean/image/http-headers-status.svg 

If would be great if you could also add a namespace declaration for 
XLink. This will make it work in Firefox :-)

xmlns:xlink="http://www.w3.org/1999/xlink"

/niklas

On 1/29/07, Niklas Gustavsson <niklas@...> wrote:
>
> If would be great if you could also add a namespace declaration for
> XLink. This will make it work in Firefox :-)
>
> xmlns:xlink="http://www.w3.org/1999/xlink"

Fixed up. Thanks for the tip :-)

Alan

Alan Dean wrote:
> An svg version now available at
> 
> http://thoughtpad.net/who/alan-dean/image/http-headers-status.svg


I still dispute the allowing POST to non-existent resources.

If it doesn't exist, how can you POST into it. 404 or 410 IMO.

Which incidentally is another condition to put on that. Hence, if anyone 
on screen readers, HTMLifying clients or similar will forgive my ASCII-art.

PUT? ->true -> (same as previous)
  |
  |false
  |
KNOWN TO HAVE EXISTED PREVIOUSLY -> true -> 410 Gone
  |
  |false
  |
404 File Not Found

I'd also add that some statuses can be calculated before all of this 
(e.g. we can sometimes say that /1/2/3 would map to something that would 
return a 403 before we even work out exactly what that something is and 
whether it exists or not).

On 1/30/07, Jon Hanna <jon@...> wrote:
> Alan Dean wrote:
> > An svg version now available at
> >
> > http://thoughtpad.net/who/alan-dean/image/http-headers-status.svg
>
>
> I still dispute the allowing POST to non-existent resources.
>
> If it doesn't exist, how can you POST into it. 404 or 410 IMO.

404 just means no representations are available (source), and doesn't
necessarily mean that there isn't any processing logic there (sink).
Most HTML form processors are this kind of resource; try invoking GET
on the "action URI" of an arbitrary form.

Of course, it's possible and useful (IME) to be able to use GET to
represent the state of the sink, but it's not required.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Mark Baker wrote:
 >> If it doesn't exist, how can you POST into it. 404 or 410 IMO.
 >
 > 404 just means no representations are available (source), and doesn't
 > necessarily mean that there isn't any processing logic there (sink).
 > Most HTML form processors are this kind of resource; try invoking GET
 > on the "action URI" of an arbitrary form.

If it's there and I can POST to it but not GET it then a GET should 
return 405 Method Not Allowed with POST in the Allow header. Then I know 
that it's there and I can POST to it.

 > Of course, it's possible and useful (IME) to be able to use GET to
 > represent the state of the sink, but it's not required.

Agreed, but a human-readable (or readable by whatever type of client the 
application is designed to cater for) error message along with the 405 
Method Not Allowed could be just as useful.

On 1/30/07, Jon Hanna <jon@...> wrote:
>
> I still dispute the allowing POST to non-existent resources.

I've had a think about this and read the spec again. So far as I can
tell, the spec does not forbid POSTing onto a missing resource. So I
have remodelled the flow to show two paths, where one permits and the
other prevents POSTing to missing resources.

>
> If it doesn't exist, how can you POST into it. 404 or 410 IMO.
>
> Which incidentally is another condition to put on that. Hence, if anyone
> on screen readers, HTMLifying clients or similar will forgive my ASCII-art.
>
> PUT? ->true -> (same as previous)
> |
> |false
> |
> KNOWN TO HAVE EXISTED PREVIOUSLY -> true -> 410 Gone
> |
> |false
> |
> 404 File Not Found
>

Good feedback - have added 410 Gone.

> I'd also add that some statuses can be calculated before all of this
> (e.g. we can sometimes say that /1/2/3 would map to something that would
> return a 403 before we even work out exactly what that something is and
> whether it exists or not).

For more completeness, I have added the resolution of status codes
prior to testing for the existence of a resource.

There is a new version of the activity diagram uploaded. The changes
are extensive.

For a list of all representations and a version history, see
http://thoughtpad.net/who/alan-dean/image/http-headers-status

I'm finding this a very useful process - thanks for the feedback everyone :-)

Regards,
Alan Dean

Hey guys, 

I'm having a bit of a disagreement with our chief architect (and head development honcho) 
about whether or not our app is restful and/or what we need to make it so. 

My first contention is that becuase your average web browser really only implements the 
GET and POST HTTP methods that you can't really code a human facing website to be 
really RESTful. Basically, IE is not a RESTful client. 

Having said that, lets assume that my first suggestion is wrong and that you be RESTful on 
a human facing website. Or application does online banking. All transactions take multiple 
steps (at a minimum, there is the form, a confirmation and a reciept, although some 
transaction like a repeating transfer into some external account have multiple form steps). 
Our architect says that the RESTful approach is to have a unique URL for every step of the 
transaction, that doing so correctly encodes all the States as resources. I argue that this is 
not the case for a few reasons:
1) It doesn't correctly include all the States as error conditions are not considered
2) That its only a coincidence of our implementation (its 5+ years old)  that a user needs 
to make several trips to the server in order to complete a transaction. We could have just 
as easily built an AJAXy UI which only makes one call to the server. This seems to me to be 
an architectural smell. 
3) That while it could make sense that one would have a series of resources which 
transform something (in this case form parameters) into some intermediate state until that 
something is ready to be POSTed to the "real" resource, it seems a contrivance.

By contrast, our current implementation hides all the steps of the transaction behind a 
single URL that the end user sees. The server code (which could be written as a RESTful 
client for a RESTful online banking service) that the user most directly interacts with is 
responsible for determining, based on the information provided, what content to send to 
the browser, either the reciept or some intermediate form. 

So.. which of us is less wrong?
Adam

"fyzixadam" <adam.vandenhoven@...> writes:

> I'm having a bit of a disagreement with our chief architect (and head development honcho) 
> about whether or not our app is restful and/or what we need to make it so. 
>
> My first contention is that becuase your average web browser really only implements the 
> GET and POST HTTP methods that you can't really code a human facing website to be 
> really RESTful. Basically, IE is not a RESTful client. 

It has a javascript engine that can do PUT and DELETE and OPTIONS and
anything else you like.

That is a well worn pattern for RESTfull clients.


> Having said that, lets assume that my first suggestion is wrong and that you be RESTful on 
> a human facing website. Or application does online banking. All transactions take multiple 
> steps (at a minimum, there is the form, a confirmation and a reciept, although some 
> transaction like a repeating transfer into some external account have multiple form steps). 
> Our architect says that the RESTful approach is to have a unique URL for every step of the 
> transaction, that doing so correctly encodes all the States as resources. I argue that this is 
> not the case for a few reasons:
> 1) It doesn't correctly include all the States as error conditions are not considered
> 2) That its only a coincidence of our implementation (its 5+ years old)  that a user needs 
> to make several trips to the server in order to complete a transaction. We could have just 
> as easily built an AJAXy UI which only makes one call to the server. This seems to me to be 
> an architectural smell. 
> 3) That while it could make sense that one would have a series of resources which 
> transform something (in this case form parameters) into some intermediate state until that 
> something is ready to be POSTed to the "real" resource, it seems a contrivance.
>
> By contrast, our current implementation hides all the steps of the transaction behind a 
> single URL that the end user sees. The server code (which could be written as a RESTful 
> client for a RESTful online banking service) that the user most directly interacts with is 
> responsible for determining, based on the information provided, what content to send to 
> the browser, either the reciept or some intermediate form. 

You don't have to encode all the states AS resources. You have to
encode the state IN the resources.


A common pattern espoused here is the POST, then PUT. It works really
well for transactional models.

You POST to create a transaction resource... and then PUT it's state
to it (perhaps repeatedly).


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

fyzixadam wrote:
> My first contention is that becuase your average web browser really only implements the 
> GET and POST HTTP methods that you can't really code a human facing website to be 
> really RESTful. Basically, IE is not a RESTful client. 

Firstly, the most popular modern browsers allow for the full use of all 
HTTP methods in AJAX (a few bugs aside).

Secondly, I don't think being restricted to GET and POST means a client 
isn't RESTful, it's just restricted in terms of what RESTful features it 
can use. In certain cases this is appropriate (it makes sense for some 
clients to be deliberately restricted to GET only - if they are meant to 
only have a read-only view on the resources in question). As such I'd 
say that GET and POST can be enough for a fully RESTful application, but 
not enough for all fully RESTful applications.

> Having said that, lets assume that my first suggestion is wrong and that you be RESTful on 
> a human facing website. Or application does online banking. All transactions take multiple 
> steps (at a minimum, there is the form, a confirmation and a reciept, although some 
> transaction like a repeating transfer into some external account have multiple form steps). 
> Our architect says that the RESTful approach is to have a unique URL for every step of the 
> transaction, that doing so correctly encodes all the States as resources. I argue that this is 
> not the case for a few reasons:
[snip]
I think you are both potentially describing RESTful applications, and 
potentially not (if other matters not stated break the constraints). 
Which of you is describing the better RESTful application is another matter.

In terms of both your questions here I get the sense that you are saying 
"there is a RESTful way of doing things". It's more accurate to say 
"some ways of doing things are RESTful, because they don't break the 
constraints of REST".

In particular, something being RESTful doesn't mean it takes full 
advantage of what REST offers, but rather it doesn't try to take 
advantage of something REST doesn't offer.

More importantly, as big a fan of REST as I am, something being RESTful 
doesn't automatically mean it doesn't suck. The not-sucking constraint 
is both more important than any constraint in REST and often harder to 
meet :)

..from Larry O'Brien called "Give it a REST", decrying the failure of WS-* in 
the real world.

http://www.sdtimes.com/printArticle/column-20070115-02.html

Probably preaching to the converted on this list, but such material is good 
to have in your kit bag, when fending off the forces of wsevil! ;-)


Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

And there's even a t-shirt for you...
http://www.cafepress.com/rest

"Web Services - Just give it a REST" http://www.cafepress.com/rest.4541012

(I put these up back in mid-2002, my how time flies)
 
I think Paul Prescod is the only one that bought - but he got the obscene
one (which I've taken down).


> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Andrzej 
> Jan Taramina
> Sent: Wednesday, January 31, 2007 12:55 PM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Great article...
> 
> ..from Larry O'Brien called "Give it a REST", decrying the 
> failure of WS-* in the real world.
> 
> http://www.sdtimes.com/printArticle/column-20070115-02.html
> 
> Probably preaching to the converted on this list, but such 
> material is good to have in your kit bag, when fending off 
> the forces of wsevil! ;-)
> 
> 
> Andrzej Jan Taramina
> Chaeron Corporation: Enterprise System Solutions
> http://www.chaeron.com
> 
> 
> 
>  
> Yahoo! Groups Links
> 
> 
> 

S. Mike Dierken wrote:
> I think Paul Prescod is the only one that bought - but he got the obscene
> one (which I've taken down).

What ever happened to Paul Prescod anyway?

  $ curl -si http://www.prescod.net | grep -i modified
  Last-Modified: Thu, 02 Jan 2003 19:10:29 GMT

His HTTP and REST lit had a tremendous impact on me.

--
Ryan

I think he's a director of program management somewhere, I think he got back
into markup technologies.
He might be at xmetal.com - I haven't spoken with him in a while.
We used to work together long time back, I should give him a call...

 

> -----Original Message-----
> From: Ryan Tomayko [mailto:rtomayko@...] 
> Sent: Wednesday, January 31, 2007 9:59 PM
> To: S. Mike Dierken
> Cc: andrzej@...; rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] Great article...
> 
> S. Mike Dierken wrote:
> > I think Paul Prescod is the only one that bought - but he got the 
> > obscene one (which I've taken down).
> 
> What ever happened to Paul Prescod anyway?
> 
>   $ curl -si http://www.prescod.net | grep -i modified
>   Last-Modified: Thu, 02 Jan 2003 19:10:29 GMT
> 
> His HTTP and REST lit had a tremendous impact on me.
> 
> --
> Ryan

Hello,

I have a question about the if-match header.
As a client, I would like to PUT a new representation of a resource
that I get in the past with entity tag "A". Therefore, I send a PUT
request with the "if-match" header.
Unfortunately, this resource has been deleted. What could be the
behaviour of the server ?
Here is an excerpt of the HTTP rfc 2616 :
If none of the entity tags match, or if "*" is given and no current
entity exists, the server MUST NOT perform the requested method".

It could be understood in 2 ways :
 - PUT the new representation because "*" has not been given
 - send 412 status because "If none of the entity tags match" may say
that effectively the "A" entity tag has been matched.

Best regards,
Thierry Boileau 

Thierry wrote:
> Hello,
> 
> I have a question about the if-match header.
> As a client, I would like to PUT a new representation of a resource
> that I get in the past with entity tag "A". Therefore, I send a PUT
> request with the "if-match" header.
> Unfortunately, this resource has been deleted. What could be the
> behaviour of the server ?

412 because the If-Match has failed.

At the client you know that this 412 means one of the following:

1. The resource was changed and hence has a different entity-tag.
2. The resource was deleted.
3. Another precondition failed.

Assuming there were no other preconditions (if there are then this is 
due to something your client is doing, and hence the extra complexity is 
coming from your application domain rather than the spec, anyway it's 
out of scope for the If-Match matter), then a GET on the URI will return 
one of:

1. A 301 response because the old resources was moved. Deal with this as 
appropriate.
2. A 2xx response with a new entity representing the resource with a new 
E-Tag. Deal with this as appropriate (most likely warning the user that 
they are going to over-write changes and asking how they would like to 
proceed).
3. A 404 or 410 response indicating the deletion that happened in your 
hypothetical example (but which we cannot assume happened). Deal with 
this as appropriate (most likely either retrying the PUT without an 
If-Match or else warning the user about the deletion and asking how they 
would like to proceed).
4. A 5xx or a 4xx (other than 404 or 410) response indicating an error.

412 Precondition Failed

I have published my interpretation of the HTTP spec regarding header
resolution at
http://thoughtpad.net/who/alan-dean/image/http-headers-status

Regards,
Alan Dean

On 2/1/07, Thierry <thboileau@...> wrote:
>
> I have a question about the if-match header.
> As a client, I would like to PUT a new representation of a resource
> that I get in the past with entity tag "A". Therefore, I send a PUT
> request with the "if-match" header.
> Unfortunately, this resource has been deleted. What could be the
> behaviour of the server ?
> Here is an excerpt of the HTTP rfc 2616 :
> If none of the entity tags match, or if "*" is given and no current
> entity exists, the server MUST NOT perform the requested method".

I'm sure this is a total noob question but I haven't been able to  
find an answer :)

My beloved has started learning ancient Greek. So I'm planning to set  
up a simple vocabulary training program ...

I imagine a central ressource called "trainer" who's picking  
exercises randomly. A request to the trainer would mean: "give me the  
next exercise you want me to complete". The trainer responds with one  
of many exercises most of the time. After having completed a certain  
number of exercises the trainee would be directed to some kind of  
summary or statistics.

How should I model this?

As the response of the trainer ressource is meant to change randomly  
for each request, should I POST to this ressource? Or should I GET it  
and redirect the client through a location header? Or do something  
else that I'm missing?

This question could probably be reduced to "How do I RESTfully throw  
a dice?"

Thanks in advance!


-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@artweb-design.de

Thierry,

Thank you for your kind comments.

I am based my interpreation of the handling of "If-Match: *" where a
resource does not exist on the following paragraph:

"The meaning of "If-Match: *" is that the method SHOULD be performed
if the representation selected by the origin server [...] exists, and
MUST NOT be performed if the representation does not exist."

from http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24

Unfortunately, the spec seems to treat this header value as a special
case - it does not specify what to do given any other conditional
header when the resource is missing. I therefore took this to mean
that any other conditional header has no effect when the resource is
missing.

This is simply my interpretation, of course, and would like to hear
the opinions of others. If an alternative interpretation gathers a
consensus then I will amend the diagram.

Regards,
Alan Dean

On 2/1/07, Thierry Boileau <thboileau@...> wrote:
> Hello Alan,
>
> First, I have to thank you for your great effort providing this so
> comprehensive activity diagram. This is really great!
>
> However, I have one question about the case where no resource is found,
> but an "If-match" header has been provided.
> If I understand your diagram, you expect a 412 status [precondition
> failed] when no resource exists and if and only if the "If-match"
> header's value equals to "*".
> I was not sure myself, therefore I've checked the HTTP RFC (which is not
> really clear), and finally posted a mail to the "REST discuss" yahoo groups.
> It seems that the test is : when no resource exists and if an "If-match"
> header has been provided (not only "*").
>
> What are you tinking about?
> Best regards,
> Thierry Boileau

On 2/1/07, Sven Fuchs <svenfuchs@...> wrote:
>
> This question could probably be reduced to "How do I RESTfully throw
> a dice?"

You could implement a dice throw as follows:

-->
GET /dice/throw

<--
302 Found
Location: /dice/4

{representation}

... perhaps you may want the client to specify the number of sides on the dice:

-->
GET /dice/throw/20

<--
302 Found
Location: /dice/11

{representation}


Regards, Alan Dean

Sven Fuchs wrote:
> This question could probably be reduced to "How do I RESTfully throw  
> a dice?"

Assuming you have no security requirements upon "cheating" this is a 
question of one activity (just what that activity is is your very 
question) mapping to one of a set of resources.

Since there is no issue in these resources being independently 
identified they can be identified by URIs that one can GET from and then 
POST answers to.

The "dice" can indeed be mapped as a redirect. It's perfectly okay to 
map it as a redirect from a GET - that entities returned from resources 
change over time is one of the inherent features of REST and this can 
just as easily be between every single request as it can over more 
clearly marked times of modification.

Hence a 307 Temporary Redirect from the "dice" resource would be 
apposite. Note that by default 307 responses are not cacheable (which 
suits your purposes) though there is nothing to stop the target of the 
redirect being cached (which is a good thing, if chance does mean a 
repeat on the dice there's no reason why the cache shouldn't be used).

If you need to guard against cheating then a different model would be 
required beyond a purely simple 307.

Alan Dean wrote:
> Unfortunately, the spec seems to treat this header value as a special
> case - it does not specify what to do given any other conditional
> header when the resource is missing.

It does indeed treat this value as a special case, though when you 
consider as a wild card it's "specialness" is reduced.

The spec *does* specify what to do when the resource is missing, but not 
as explicitly.

Consider If-Match: "abcde" when the resource is missing.

Does this match an available resource? The answer is clearly "no".

Now, when we consider the other rule about "If the request would, 
without the If-Match header field, result in anything other than a 2xx 
or 412 status, then the If-Match header MUST be ignored." this means 
that if the request is GET we will get a 404, but with PUT we will get a 
412 (I'm simplifying my assuming that there are no other factors 
affecting the status code returned).

On 2/1/07, Jon Hanna <jon@...> wrote:
>
> Alan Dean wrote:
> > Unfortunately, the spec seems to treat this header value as a special
> > case - it does not specify what to do given any other conditional
> > header when the resource is missing.
>
> It does indeed treat this value as a special case, though when you
> consider as a wild card it's "specialness" is reduced.
>
> The spec *does* specify what to do when the resource is missing, but not
> as explicitly.
>
> Consider If-Match: "abcde" when the resource is missing.
>
> Does this match an available resource? The answer is clearly "no".
>
> Now, when we consider the other rule about "If the request would,
> without the If-Match header field, result in anything other than a 2xx
> or 412 status, then the If-Match header MUST be ignored." this means
> that if the request is GET we will get a 404, but with PUT we will get a
> 412 (I'm simplifying my assuming that there are no other factors
> affecting the status code returned).

If I understand your contention correctly, you are saying that:

If the resource is missing;
   and any value at all is specified in If-Match
      then return 412 Precondition Failed

I can see the logic of how you reached that conclusion, but I am left
wondering "if that is the case, why does the spec bother to stipulate
the case of the wildcard - why not stipulate 'any' instead?"

Hmmmmm.....

Alan

Alan Dean wrote:
> If I understand your contention correctly, you are saying that:
> 
> If the resource is missing;
>    and any value at all is specified in If-Match
>       then return 412 Precondition Failed

Nope.

	If the resource is missing
		and any value at all is specified in If-Match
			and request would otherwise result in 2xx result
				the 412 Precondition Failed.

> I can see the logic of how you reached that conclusion, but I am left
> wondering "if that is the case, why does the spec bother to stipulate
> the case of the wildcard - why not stipulate 'any' instead?"

Because that's the only condition underwhich * causes a 412.

If-Match: "abcde" can also cause a 412 if there is an entity to return, 
but none with that E-tag OR if there is no entity at all.

If-Match: * can *only* cause a 412 if there is no entity to return.

On 2/1/07, Sven Fuchs <svenfuchs@...> wrote:
> This question could probably be reduced to "How do I RESTfully throw
> a dice?"

How about;

GET /trainer

->

200 Ok
Content-Type: text/uri-list
http://example.org/activity/9

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Hello,

This is not strictly speaking related to REST per se, but... perhaps 
someone could point me to the right direction nonetheless...

To make a long story short, I'm a bit confused on how the different 
HTTP entity transformations work together... or not. In other words, 
from an HTTP server perspective, how does one properly combine things 
like entity tags, conditional requests, ranges and content encoding to 
name a few?

Even after going through Jeffrey C. Mogul's "Clarifying the 
Fundamentals of HTTP" and such, I'm not the wiser :P

http://www2002.org/CDROM/refereed/444.pdf

Any pointers, guidelines, opinions or advises very welcome :)

Thanks in advance.

Cheers,

PA.

PA schrieb:
> 
> 
> Hello,
> 
> This is not strictly speaking related to REST per se, but... perhaps
> someone could point me to the right direction nonetheless. ..
> 
> To make a long story short, I'm a bit confused on how the different
> HTTP entity transformations work together... or not. In other words,
>  >from an HTTP server perspective, how does one properly combine things
> like entity tags, conditional requests, ranges and content encoding to
> name a few?
> 
> Even after going through Jeffrey C. Mogul's "Clarifying the
> Fundamentals of HTTP" and such, I'm not the wiser :P
> 
> http://www2002. org/CDROM/ refereed/ 444.pdf 
> <http://www2002.org/CDROM/refereed/444.pdf>
> 
> Any pointers, guidelines, opinions or advises very welcome :)

Here's your pointer: (:-) come over to the (former) HTTP WG'smailing 
list: <http://lists.w3.org/Archives/Public/ietf-http-wg/>.

Best regards, Julian

> I imagine a central ressource called "trainer" who's picking 
> exercises randomly. A request to the trainer would mean: 
> "give me the next exercise you want me to complete". The 
> trainer responds with one of many exercises most of the time. 
> After having completed a certain number of exercises the 
> trainee would be directed to some kind of summary or statistics.
> 
> How should I model this?
> 
> As the response of the trainer ressource is meant to change 
> randomly for each request, should I POST to this ressource? 
> Or should I GET it and redirect the client through a location 
> header? Or do something else that I'm missing?
The response is not meant to change randomly - you said "... want me to
complete". Until you've indicated that your state is 'complete', then the
response should remain unchanged (in order to take into consideration the
failure to retrieve the initial response completely).

Here's another approach - each lesson retrieved has a link to the next
lesson. The client decides when it is complete, then retrieves the next
lesson. That next lesson has yet another link to yet another lesson. And so
on.

GET /lessons/99

200 Ok
Content-Type: application/socratic.lesson+xml

<lesson next='/lessons/47'>
 some lessons to be learned
</lesson>






> -----Original Message-----
> From: S. Mike Dierken [mailto:dierken@...] 
> Sent: Thursday, February 01, 2007 9:23 PM
> To: 'Sven Fuchs'; 'rest-discuss@yahoogroups.com'
> Subject: RE: [rest-discuss] How do I RESTfully throw a dice? 
> (or: randomized responses)
> 
> > I imagine a central ressource called "trainer" who's 
> picking exercises 
> > randomly. A request to the trainer would mean:
> > "give me the next exercise you want me to complete". The trainer 
> > responds with one of many exercises most of the time.
> > After having completed a certain number of exercises the 
> trainee would 
> > be directed to some kind of summary or statistics.
> > 
> > How should I model this?
> > 
> > As the response of the trainer ressource is meant to change 
> randomly 
> > for each request, should I POST to this ressource?
> > Or should I GET it and redirect the client through a 
> location header? 
> > Or do something else that I'm missing?
> The response is not meant to change randomly - you said "... 
> want me to complete". Until you've indicated that your state 
> is 'complete', then the response should remain unchanged (in 
> order to take into consideration the failure to retrieve the 
> initial response completely).
> 
> 

Hi,

I've never built a REST app but am thinking of going that direction
with the next major version of a content repository API used by my
employer.  There's a few things I'm not sure how to model, the main
one being transactions. I'm hoping for some guidance on my path to
grokking REST.

APP is looking interesting, since most of what we need maps pretty
well to member entries, feeds, and media resources. The introspection
feature might be useful too.

But what about this use case? A third party comes along and licenses
10,000 documents to us.  There are lots of cross-links among those
documents, so a requirement in the contract is that we must load the
entire set successfully, or none at all.

Leaving this up to the client is not an option. This is part of a SOA,
and there's currently four clients.

APP doesn't seem to say anything about transactions, so I'm assuming
that it's up to me to find a more generally REST-y solution.

The one obvious idea that occurs to me is to define two new resources,
a transaction manager and a transaction resource.  A transaction is
really just a collection.  To create a new transaction, POST to the
transaction manager with a list of the resource URIs you want to
modify. It initializes the transaction by copying those members, and
returns the URI of your new transaction.

GET the transaction resource to see a list of member URIs, as usual.
PUT or DELETE any of those members as usual.  POST to the transaction
to add new members as usual. To abort, just DELETE the transaction.

If this all sounds familiar, maybe it's reminiscent of:
http://example.com/subversion/branches
http://example.com/subversion/trunk

But what does a "commit" look like? I don't see an appropriate verb
other than PUT, so I see two options:

1) PUT the URI of the original collection to the transaction.  This is
a nice and simple message, but means the transaction has to be a
little smarter than a normal collection.

2) PUT the URIs of the transaction and the original collection to the
transaction manager. This would be interpreted like "merge the
contents of URI 1 into URI 2".

(I first thought of POSTing a special message to the T.M. to commit,
but realized that would look too much like creating a transaction. It
smells RPC. I figure any time I can't tell what's going on by looking
at a simple access log, it's not really REST!)

Either way, we should check mod times and if a conflict is detected,
return an error. 409?

How's that sound? Better ideas?


P.S. this is my first post to the list. Hello!

-- 

Paul Winkler
http://www.slinkp.com

Paul Winkler <pw_lists@...> writes:

> (I first thought of POSTing a special message to the T.M. to commit,
> but realized that would look too much like creating a transaction. It
> smells RPC. I figure any time I can't tell what's going on by looking
> at a simple access log, it's not really REST!)
>
> Either way, we should check mod times and if a conflict is detected,
> return an error. 409?
>
> How's that sound? Better ideas?

We have discussed in the past:

POST /someresource
=> 201 /someresource/1

POST /someresource/1 { data }
=> 201

and again... and again... until you've added all the parts of the
transaction

GET /someresource
=> 200 { representaion of transaction data }

PUT /someresource  { what you just GOT back }
=> 200

and transaction ended.


> P.S. this is my first post to the list. Hello!

Hello!


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Hi Paul,

On 02.02.2007, at 06:16, Paul Winkler wrote:

> Hi,
>
> I've never built a REST app but am thinking of going that direction
> with the next major version of a content repository API used by my
> employer.

You might also want to check out JSR 170[1]

>
> APP is looking interesting, since most of what we need maps pretty
> well to member entries, feeds, and media resources. The introspection
> feature might be useful too.

Yes, APP is indeed very interesting towards that end. I tend to see  
APP/Atom to
provide for the machine-to-machine Web what HTML is for the machine-2- 
human
web - it provides a set of semantics to get stuff done.


>
> But what about this use case? A third party comes along and licenses
> 10,000 documents to us.  There are lots of cross-links among those
> documents, so a requirement in the contract is that we must load the
> entire set successfully, or none at all.
>
> Leaving this up to the client is not an option. This is part of a SOA,
> and there's currently four clients.
>
> APP doesn't seem to say anything about transactions, so I'm assuming
> that it's up to me to find a more generally REST-y solution.

Yes. The perfect thing to do this would be an APP extension.

>
> The one obvious idea that occurs to me is to define two new resources,
> a transaction manager and a transaction resource.  A transaction is
> really just a collection.  To create a new transaction, POST to the
> transaction manager with a list of the resource URIs you want to
> modify. It initializes the transaction by copying those members, and
> returns the URI of your new transaction.
>
> GET the transaction resource to see a list of member URIs, as usual.
> PUT or DELETE any of those members as usual.  POST to the transaction
> to add new members as usual. To abort, just DELETE the transaction.

Hmm, IMHO that is close but not quite on the point. What you really  
want is
to group together a bunch of requests; you want to tell the server  
that the
10000 POSTs you are doing form a logical unit.
The way to generally do this with HTTP (scan the list archives for  
this) is
to include a transaction idenifier (URI) in each request with a  
request HTTP
header.

>
> But what does a "commit" look like? I don't see an appropriate verb
> other than PUT, so I see two options:
>

That is a missing piece, yes. You need a way to to tell the  
transaction to
commit or rollback.

Here is my sketch how all this could be done with Atom:

- A server that provides transactionaliy declares in its service  
document that
   a) there is a transaction collection and b) what other collections  
support transactions.
  (You do this via James Snell's atompub-feature extension[2])

- POST to the transaction collection to create a new transaction; the  
URI of the transaction
   is the Location returned by the server in the 201 Created response.

- include that URI in all subsequent requests to the other collections

   POST /documents
   Transaction-URI: http://foo.org/transactions/3

   [document1 of 10000]

Afterwards, PUT to the ransaction a representation that sets it to the
'commited' state. This could for example be done with an APP control  
extension,
as in:

PUT /transactions/3

<entry>
   <!-- .... -->
   <app:control>
     <tx:commit>
   </app:control>
</entry>

Note that all this applies only to local transactions, managing  
distributed transactions
would need to involve a transaction manager and all the 2PC  
requirements. OTH, in
an environment that makes REST a good choice doing 2PC is usually the  
thing *not* to
do - you'd need other forms of coordination (this is next on my list  
of stuff to look at, so I
really cannot provide any guidance here now).

HTH,

Jan

[1]http://www.jcp.org/en/jsr/detail?id=170
[2]http://tools.ietf.org/id/draft-snell-atompub-feature-01.txt

> 1) PUT the URI of the original collection to the transaction.  This is
> a nice and simple message, but means the transaction has to be a
> little smarter than a normal collection.
>
> 2) PUT the URIs of the transaction and the original collection to the
> transaction manager. This would be interpreted like "merge the
> contents of URI 1 into URI 2".
>
> (I first thought of POSTing a special message to the T.M. to commit,
> but realized that would look too much like creating a transaction. It
> smells RPC. I figure any time I can't tell what's going on by looking
> at a simple access log, it's not really REST!)
>
> Either way, we should check mod times and if a conflict is detected,
> return an error. 409?
>
> How's that sound? Better ideas?
>
>
> P.S. this is my first post to the list. Hello!
>
> -- 
>
> Paul Winkler
> http://www.slinkp.com
>
>
>
> Yahoo! Groups Links
>
>
>

Am 02.02.2007 um 06:23 schrieb S. Mike Dierken:
> The response is not meant to change randomly - you said "... want  
> me to
> complete". Until you've indicated that your state is 'complete',  
> then the
> response should remain unchanged (in order to take into  
> consideration the
> failure to retrieve the initial response completely).

Hmm, yes. That's probably due to my bad English.

What I've meant was that the trainer selects one of many exercises  
that the trainee is asked to take. An exercise may be as simple as a  
question with a multiple choice of answers. Where the random-ness  
(and thus, the dice) comes into play is where the trainer selects an  
exercise. Though this selection might involve further criteria at  
some time (e.g. critera based on the trainees learning process), in  
it's simplest form it is just a pure random selection.

When the trainee gives an incorrect answer the chances of this  
exercise to be re-selected might be increased. Or not. I'm not yet  
completely sure about this (I'm thinking about some kind of simple  
flashcard system [1]). But I'm tending to a model where the order of  
the exercises is unpredictable / shuffles randomly.

[1] http://en.wikipedia.org/wiki/Flashcard


-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@artweb-design.de

Thanks a lot, guys, for all the kind and quite illuminating responses!

Am 01.02.2007 um 17:59 schrieb Alan Dean:
> You could implement a dice throw as follows:
> -->
> GET /dice/throw
> <--
> 302 Found
> Location: /dice/4

I now have the feeling that I've asked for something pretty obvious. ;)

Using curl I've seen that this even seems to be exactly the behavious  
that Ruby on Rails shows by default when doing a redirect. So as I'm  
going to use Ruby on Rails that's probably the way for me to go.


Am 01.02.2007 um 17:59 schrieb Jon Hanna:
> The "dice" can indeed be mapped as a redirect. It's perfectly okay to
> map it as a redirect from a GET - that entities returned from  
> resources
> change over time is one of the inherent features of REST and this can
> just as easily be between every single request as it can over more
> clearly marked times of modification.

What initially irritated me (and still does so) was the consideration  
that GET has to be idempotent. I had the impression that redirecting  
to different locations would mean issuing entirely different  
responses (and thus violating GETs idempontence). I suppose I've been  
wrong on this? But what's the meaning of idempotence than in this case?

> Hence a 307 Temporary Redirect from the "dice" resource would be
> apposite. Note that by default 307 responses are not cacheable (which
> suits your purposes) though there is nothing to stop the target of the
> redirect being cached (which is a good thing, if chance does mean a
> repeat on the dice there's no reason why the cache shouldn't be used).

Do you also agree with the 302 Found response that Alan proposed?  
Looking at the HTTP spec, am I right that there's no difference  
between these both responses as far as GET requests are concerned?

> If you need to guard against cheating then a different model would be
> required beyond a purely simple 307.

No, cheating is not a design consideration right now.

Thanks again for answering!


-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@artweb-design.de

Alan Dean wrote:
> 
> 
> On 2/1/07, Sven Fuchs <svenfuchs@... 
> <mailto:svenfuchs%40artweb-design.de>> wrote:
>  >
>  > This question could probably be reduced to "How do I RESTfully throw
>  > a dice?"
> 
> You could implement a dice throw as follows:
> 
> -->
> GET /dice/throw
> 
> <--
> 302 Found
> Location: /dice/4
> 
> {representation}

To throw a dice, use POST. To find out what the number was, use GET. To 
cheat, use PUT.

cheers
Bill

Am 01.02.2007 um 19:56 schrieb Mark Baker:
> How about;
> GET /trainer
> ->
> 200 Ok
> Content-Type: text/uri-list
> http://example.org/activity/9

Cool :)

I've not been aware of this content-type. I (think I) understand how  
this kind of response exactly models what I've been asking for.

But as I'm going to implement this as a web application (using a  
browser as a client) I right now think that a 302 Found/Location  
redirect should do it.

-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@...

Ok, but you needn't use text/uri-list.   text/html would work as well
(with lots more content, of course).  The point is simply that you can
treat the die/dice as a random data source and therefore a vanilla
GET/200 exchange should suffice.

On 2/2/07, Sven Fuchs <svenfuchs@...> wrote:
> Am 01.02.2007 um 19:56 schrieb Mark Baker:
> > How about;
> > GET /trainer
> > ->
> > 200 Ok
> > Content-Type: text/uri-list
> > http://example.org/activity/9
>
> Cool :)
>
> I've not been aware of this content-type. I (think I) understand how
> this kind of response exactly models what I've been asking for.
>
> But as I'm going to implement this as a web application (using a
> browser as a client) I right now think that a 302 Found/Location
> redirect should do it.
>
> --
> sven fuchs                      fon:  +49 (58 45) 98 89 58
> artweb design                   fax:  +49 (58 45) 98 89 57
> breite stra�e 65                www: http://www.artweb-design.de
> de-29468 bergen         mail: svenfuchs@...
>
>
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On 2 Feb 2007, at 11:36, Bill de hOra wrote:
> To throw a dice, use POST.
POST /dice/throw
->
HTTP 1.1 201 Created
Location: /dice/throw/90802
Content-type: text/plain

6

> To find out what the number was, use GET.
GET /dice/throw
-> //an Atom feed of recent throws

GET /dice/throw/90802
-> //the value of an individual throw, as text, HTML, XML,
    whatever the client asks for

> To cheat, use PUT.
run away!

Paul
--
http://blog.whatfettle.com


--
http://blog.whatfettle.com

Bill de hOra wrote:
> To throw a dice, use POST. To find out what the number was, use GET. To 
> cheat, use PUT.

For a user-throwable die, yes.

For an automatic die were the user just sees the thrown result GET the 
uncacheable result.

On Fri, Feb 02, 2007 at 09:59:31AM +0100, Jan Algermissen wrote:
> Here is my sketch how all this could be done with Atom:
> 
> - A server that provides transactionaliy declares in its service  
> document that
>   a) there is a transaction collection and b) what other collections  
> support transactions.
>  (You do this via James Snell's atompub-feature extension[2])

That looks interesting, thanks!

> - POST to the transaction collection to create a new transaction; the  
> URI of the transaction
>   is the Location returned by the server in the 201 Created response.
> 
> - include that URI in all subsequent requests to the other collections
> 
>   POST /documents
>   Transaction-URI: http://foo.org/transactions/3

Okay. I hadn't looked into the idea of custom headers.  Somehow I
assumed that wasn't kosher, since it means the client is assuming
non-standard capabilities on the server. I am still lacking in
rest-fu.

> Afterwards, PUT to the ransaction a representation that sets it to the
> 'commited' state. This could for example be done with an APP control  
> extension,
> as in:
> 
> PUT /transactions/3
> 
> <entry>
>   <!-- .... -->
>   <app:control>
>     <tx:commit>
>   </app:control>
> </entry>

Aha, I hadn't read section 12 of the protocol draft.

> Note that all this applies only to local transactions
...

Yeah, distributed transactions seems like YAGNI for this project.
Thanks!

-- 

Paul Winkler
http://www.slinkp.com

On Fri, Feb 02, 2007 at 08:55:55AM +0000, Nic James Ferrier wrote:
> Paul Winkler <pw_lists@...> writes:
> 
> > (I first thought of POSTing a special message to the T.M. to commit,
> > but realized that would look too much like creating a transaction. It
> > smells RPC. I figure any time I can't tell what's going on by looking
> > at a simple access log, it's not really REST!)
> >
> > Either way, we should check mod times and if a conflict is detected,
> > return an error. 409?
> >
> > How's that sound? Better ideas?
> 
> We have discussed in the past:

Yeah, I'm starting to find my way in the archives, lots of stuff to
catch up on...

> POST /someresource
> => 201 /someresource/1
>
> POST /someresource/1 { data }
> => 201
> 
> and again... and again... until you've added all the parts of the
> transaction
> 
> GET /someresource
> => 200 { representaion of transaction data }

Not sure what resource you meant here. Is that the right URI?

Also, if I understand you correctly, you're talking about transferring
the entire transaction state.  That sounds fine for something small
like a typical online shopping cart, but for a content repository that
isn't going to scale. Think bulk loading. Potentially gigabytes of
data.

> PUT /someresource  { what you just GOT back }
> => 200
>
> and transaction ended.

Ditto. This will only work for me if it's by reference, not by value.

Thanks for the input!

-- 

Paul Winkler
http://www.slinkp.com

Paul Winkler <pw_lists@...> writes:

>> GET /someresource
>> => 200 { representaion of transaction data }
>
> Not sure what resource you meant here. Is that the right URI?

Yes. You get a representation of the entire transaction state.


> Also, if I understand you correctly, you're talking about transferring
> the entire transaction state.  That sounds fine for something small
> like a typical online shopping cart, but for a content repository that
> isn't going to scale. Think bulk loading. Potentially gigabytes of
> data.

Sure. But we're talking about a representation of the transaction
state. It doesn't have to show you the whole data set: maybe just
lists of URIs?


>> PUT /someresource  { what you just GOT back }
>> => 200
>>
>> and transaction ended.
>
> Ditto. This will only work for me if it's by reference, not by
> value.

Ditto.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Fri, Feb 02, 2007 at 05:23:16PM +0000, Nic James Ferrier wrote:
> Sure. But we're talking about a representation of the transaction
> state. It doesn't have to show you the whole data set: maybe just
> lists of URIs?

Ah, I misread. Thanks.

-- 

Paul Winkler
http://www.slinkp.com

On Fri, Feb 02, 2007 at 09:59:31AM +0100, Jan Algermissen wrote:
> You might also want to check out JSR 170[1]

Thanks for the link, but AFAICT it's not really useful
if neither the client or the server is Java ;-)
Nearly everything here is either Ruby or Python nowadays.

-- 

Paul Winkler
http://www.slinkp.com

On 02.02.2007, at 18:01, Paul Winkler wrote:

>>
>>   POST /documents
>>   Transaction-URI: http://foo.org/transactions/3
>
> Okay. I hadn't looked into the idea of custom headers.  Somehow I
> assumed that wasn't kosher,

Hmm, IMHO it is ok, since client and server share the semantics  
provided in the APP extension and if the extension defines a new HTTP  
header then they should both be aware of it. Others mustIgnore the  
header.

Besides that, you could also include the Transaction URI in the Atom  
envelope (the extension could define an additional control element  
element)...well, except for DELETE requests.


> since it means the client is assuming
> non-standard capabilities on the server.

Yes, it does. Bit it does so only because the server declared that it  
(well, the collection) supports a specific feature. It is this  
feature that is the *reason* for the client to pick that collection  
and not another one. Think of it as late binding of the client  
component to the server component based on capabilities.

With SOAP/WSDL components late-bind based on the API, with HTTP/Atom  
they late-bind based on declared capabilities (or declared type if  
you want).

Gues what is more flexible :-)
(I'd also argue that the former involves the latter anyway and thus  
is just more work, unnecessary overhead, obsolete  
complexity....eventually wasted time and money).


> I am still lacking in
> rest-fu.

What is 'rest-fu' ?

Jan

Hi,

regarding late-binding of components based on declared capabilities:

It just occurred to me that this is a major difference between REST  
and messaging systems; in a messaging system, the connections between  
the components (data providers and data sinks) is static (configured)  
and cannot change dynamically. This is so, because it is not possible  
to say something about the sinks (to declare their capabilities) and  
providers would have no base to make a choice on.

Just mumbling...

Jan

> > You might also want to check out JSR 170[1]
>
>Thanks for the link, but AFAICT it's not really useful
>if neither the client or the server is Java ;-)

Be careful in discounting it just because of that. I've
found reading through some JSRs to be very helpful even
though I don't do Java. They can sometimes give you good
design ideas. (I haven't looked at this particular one
to know if it would in this situation or not...)

Cheers,
Harley Pebley
www.skylark-software.com 

Stikkit's new APIs look to be one of the more RESTful I've seen:
http://stikkit.com/api

Patrick Breitenbach
PayPal

Not bad. The docs look shiny.
Kind of odd that they would use PUT to 'toggle' the state of a
resource. PUT is supposed to be idempotent and 'toggle' is the
opposite of idempotent. Also, 'share/unshare' probably could be merged
into 'sharing', where the content describes whether something is
shared or not. I also think it's funny that they use a numerical
bitmask for specifying multiple 'types'.

The documentation doesn't describe the response headers much. Given
that api_key can be omitted when using Authorization request header,
the resource identifier becomes vague  - for example
"/stikkits?api_key=xyz" becomes "/stikkits". The response should
indicate that the entity varies by the user, or the request could
specify /whose/ stikkits are being talked about, and the authorization
header would be used in part to determine whether the request should
be allowed or not.




On 2/2/07, pat_breitenbach <pat_breitenbach@...> wrote:
> Stikkit's new APIs look to be one of the more RESTful I've seen:
> http://stikkit.com/api
>
> Patrick Breitenbach
> PayPal
>
>
>
>
> Yahoo! Groups Links
>
>
>
>

On Tue, 2007-01-30 at 12:29 +0000, Jon Hanna wrote:
> PUT? ->true -> (same as previous)
> |
> |false
> |
> KNOWN TO HAVE EXISTED PREVIOUSLY -> true -> 410 Gone
> |
> |false
> |
> 404 File Not Found

I think that text should read more like:
"Known that it will never exist again" and point to "410 Gone, or 404".
If it might come back, 404 is still the right code. 404 is allowed in
either case:

"The requested resource is no longer available at the server and no
forwarding address is known. This condition is expected to be
considered permanent." - rfc2616

Benjamin

On Thu, 2007-02-01 at 15:02 +0100, Sven Fuchs wrote:
> I imagine a central ressource called "trainer" who's picking 
> exercises randomly. A request to the trainer would mean: "give me the 
> next exercise you want me to complete". The trainer responds with one 
> of many exercises most of the time. After having completed a certain 
> number of exercises the trainee would be directed to some kind of 
> summary or statistics.

You have mentioned that in its simplest form this is throwing a die,
however there seem to be more complex forms involved as well. The
trainer may have to consider what has already been completed in order to
make an appropriate decision. That means that the list of what has been
completed has to be included explicitly or implicitly in the url.

Explicitly (client keeps track of which are completed):
http://example.com/thetrainer?completed=1+2+3+4

Implicitly (server keeps track of which are completed):
http://example.com/thetrainer?student=foo
(add authentication details here?)

In the client-side case you would likely need to be rewriting hrefs in
pages your return to the student to include the list of completed items.
In the server-side case you would likely need the client to PUT or POST
information about completed courses, possibly in the form of completed
exam papers for example.

Benjamin.

On 2/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
>
> On Tue, 2007-01-30 at 12:29 +0000, Jon Hanna wrote:
> > PUT? ->true -> (same as previous)
> > |
> > |false
> > |
> > KNOWN TO HAVE EXISTED PREVIOUSLY -> true -> 410 Gone
> > |
> > |false
> > |
> > 404 File Not Found
>
> I think that text should read more like:
> "Known that it will never exist again" and point to "410 Gone, or 404".
> If it might come back, 404 is still the right code. 404 is allowed in
> either case:
>
> "The requested resource is no longer available at the server and no
> forwarding address is known. This condition is expected to be
> considered permanent." - rfc2616

OK, fair point. It does however raise the question: "What should
happen if a PUT is made to a resource where it is known that it will
never exist again?"

Alan

On Fri, 2007-02-02 at 00:16 -0500, Paul Winkler wrote:
> I've never built a REST app but am thinking of going that direction
> with the next major version of a content repository API used by my
> employer. There's a few things I'm not sure how to model, the main
> one being transactions. I'm hoping for some guidance on my path to
> grokking REST.
...
> But what about this use case? A third party comes along and licenses
> 10,000 documents to us. There are lots of cross-links among those
> documents, so a requirement in the contract is that we must load the
> entire set successfully, or none at all.

There are two basic approaches here:
1. Model a transaction over multiple small edits
2. Make a resource available that allows the user to operate on the
entire state they want to modify as one request

The former has various implementations, but is painful to implement.
Part of that pain is because it butts up against the "stateless between
requests" constraint of REST. You transmit a bit of what you want to do,
then another bit in another request, and then finally request that all
of the bits you requested actually happen. This may be necessary if the
client has to consult current state during the transaction, however
thinking of a REST service in the same way you think about a database is
usually a mistake.

My suggestion is to use a resource that allows them to do everything
they want as one operation. Without a more detailed explaination of what
the customer might be doing it is hard to be specific, but let's look at
an example where they want to publish a thousand atom articles:

>>>
POST http://example.com/newentries
<atom>
   <entry>
     entry 1
   </entry>
   <entry>
     entry 2
   </entry>
...
   <entry>
     entry 1000
   </entry>
</atom>
<<<
200 OK

You can use a POE technique to ensure that this operation can be safely
retried if the client recieves no response.

What about updating existing entries? Perhaps something like this would
work:

PUT http://example.com/select?entries=http://example.com/0001
+http://example.com/0002...+http://example.com/1000
<atom>
   <entry xml:base="http://example.com/0001">
     entry 1
   </entry>
   <entry xml:base="http://example.com/0002">
     entry 2
   </entry>
...
   <entry xml:base="http://example.com/1000">
     entry 1000
   </entry>
</atom>

Whether attributes to identify each entry being updated are needed or
whether the order can be determined by the query is probably up for
debate, as is whether or not xml:base has strong enough semantics to
indicate which entry is which. This approach ultimately boils down to
finding a url that represents all of the data you want to update,
preferrably by filling out a server-provided template or form to locate
the data.

In my opinion, online services of all kinds (From REST to WS-*) will
tend to perform, scale and behave better when a single request is a
single request. Once the request is received, it is the responsbility of
the service that recieves the request to ensure it is treated as an
atomic update.

Benjamin

On Sun, 2007-01-28 at 12:40 +1100, Mark Nottingham wrote:
> On 2007/01/27, at 4:32 PM, Benjamin Carlyle wrote:
> > On Sat, 2007-01-20 at 19:57 +0000, Bill de hOra wrote:
> >> Start here:
> >> http://www.mnot.net/drafts/draft-nottingham-http-poe-00.txt
> >> http://www.dehora.net/doc/httplr/draft-httplr-01.html
> > Problems with POE:
> > * The specification does not cover how the POE resource is created.
> That's intentional :)
> > Presumably, it is through a POST which could lead to a chicken and
> egg
> > situation.
> Sending a POST to get the form is one way, but not the only.
> 
> Another would be to use GET, and assure that the response isn't 
> cacheable; there are a number of ways to assure that the links you've 
> given out don't collide without keeping a list of them, the easiest 
> involving timestamps (along with some other information) or GUIDs.
...

Well, let's start with a base problem statement:

I have some state that I want to append to a resource. The right method
according to HTTP is POST, but if I don't get a response to my POST I
don't know whether or not to retry.

So here are the strategies I can think of seeing so far:
1. Have the user observe some property of the system to determine
whether to retry themselves. In SCADA this might be to observe a change
in voltage before deciding whether or not to retry a circuit-breaker
trip. This can be automated as another SCADA concept: "Target state
monitoring". Regardless of the reponse we recieved, did the resource
actually reach the state we intended?

2. Select and execute. This is another SCADA idea. You first prime the
resource for operation. Only primed resources can have an operation
perfomed on them, and they automatically unprime when that operation
takes place.

3. Create a channel to operate through. The channel is designed to block
duplicate requests in a way that the client can be sure means their
request went through. Both HTTPLR and POE roughly follow this approach,
I think.

4. Always model the append as the creation of a new resource. Make the
creation of the resource (like the creation of the channel) a safe
operation that consumes a little server-side state but otherwise as no
operational effect. Once the resource has been created at least once,
PUT the data you would have POSTed as many times as necessary to be sure
it has gone through.

5. Do TCP-like sequence numbering at the message level

I think the channel concept and the new resource concepts have similar
characteristics. The channel concept would seem to perform better
whenever we don't want to create new resource for the created state, and
may also handle channel teardown more gracefully. I think the new
resource approach is conceptually simpler, at least on the face of it.
Instead of a channel concept we just have the concept of the new
resource whose creation you requested.

POE tries to solve the problem of how to interact with the channel, and
leaves the channel creation process up to the implementation. Perhaps
this is a good thing. However you'll still need to deal with any new
resource you have created through a POST to the channel. Hrmmm... let's
write some pseudo-code:

Channel approach:
try
{
    getChannel:
    channel = RequestChannel(using POST or uncachable GET);
}
catch (NoResponse)
{
    // old school psedo-code :)
    GOTO getChannel;
}
catch (...)
{
    // handle failure - request not processed, can resubmit
}

try
{
    sendPOST:
    resource = channel.POST(my content);
    // save resource url away for later use, if any
}
catch (NoResponse)
{
    GOTO sendPOST;
}
catch (...)
{
    // failed, may be able to tell whether or not request was
    // procssed if we only sent once
}

New Resource approach:
try
{
    getResource:
    resource = RequestResource(using POST or uncachable GET);
}
catch (NoResponse)
{
    GOTO getResource;
}
catch (...)
{
    // handle failure - data not submitted, can resubmit
}

try
{
    sendPUT:
    resource.PUT(my content);
}
catch (NoResponse)
{
    GOTO sendPUT;
}
catch (...)
{
    // failed, may be able to tell whether or not request was
    // procssed if we only sent once. Can resubmit.
}

The main problems with both cases are where the channel or new resource
could time out before the client gives up on things. In a client-server
relationship the client is responsible for pushing the sequence through
to completion, and the server is just responsible for reasonably
fulfilling client requests.

If the server reclaims its channel or resource state leading to a failed
PUT, it isn't going to be possible to restart the request sequence
without risking duplicate sumbission again. The channel approach offers
an optimisation of allowing the client to DELETE the channel to free up
resources. This may mean that servers need to reap potentially-leaked
resources less agressively.

The resource-based approach also introduces a problem by aliasing the
channel and created resource. If the created resource has a short
lifetime, it may be equivalent to an early timeout for client purposes.
Say the resource's PUT succeeds, but the response associated with this
is lost. When the next PUT comes in it gets a 404. Was the data
submitted or not? Should the request to submit (say) an atom entry
processed, or should it be retried?

> I don't see how sending a POST to get the POE link leads to a
> chicken- 
> and-egg problem, unless you also need the "get the form" operation 
> (which really should be a GET) to be reliable as well. Even if you 
> did, you can always bootstrap it with one that isn't required to be 
> reliable.

I see your point. I think your approach is more similar to HTTPLR than I
originally surmised.

On Sat, 2007-01-27 at 15:28 +0000, Bill de hOra wrote: 
> Benjamin Carlyle wrote:
> In light of this I prefer the
> > channel concept to simply be replaced by the concept of a created
> > resource.
> Maybe. Where you're worried about the reality of timeouts, I'm
> worried 
> about the reality of HTTPLR acting as a gateway for MOMs.

So you would write your problem statement differently:
I have a message that I want to transmit to a likely unRESTful remote
system using a POST request. I don't want it to recieve the message
twice.

> > * I think there is some danger that the message could be read to be
> a
> > whole HTTP request or SOAP request or other request that needs to be
> > delivered. That interpretation doesn't smell right to me, and I
> think
> > that any suggestion of message transfer should be explicitly avoided
> in
> > favour of state transfer.
> Again, maybe. Did you see any testable/operational consequences?

Only that it may lead to a more complex system that might muddy the
waters a little. I think the different problem statements may infer
different solution spaces... however I'm not completely sure of this
line of thought as yet.

Benjamin.

On 2/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> So here are the strategies I can think of seeing so far:
> 1. Have the user observe some property of the system to determine
> whether to retry themselves. In SCADA this might be to observe a change
> in voltage before deciding whether or not to retry a circuit-breaker
> trip. This can be automated as another SCADA concept: "Target state
> monitoring". Regardless of the reponse we recieved, did the resource
> actually reach the state we intended?

I've found this approach useful in the past, but with a caveat; if you
look for a specific value then that would be an implementation
dependency.

A technique I've used once was to have the client send an HTTP header
in the POST request which played a role sort of like a client-side
etag with respect to the request body.  The server, upon receiving the
message and updating the state of the resource, would return another
header containing a hash of the last days worth of tags (which wasn't
many) on GET requests to that resource so that it could check if *its*
update was applied.

Interesting post...

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On Sat, 2007-01-27 at 11:32 +0100, Jan Algermissen wrote:
> The model I am thinking about to achieve POE is based on the use of  
> Atom and the inclusion of an ID in the POST body (or an HTTP header).  
> POE aware clients would receive the ID to use from a factory, non-POE  
> aware clients would just do the normal POST.

One of my REST design instincts is that whenever I see an ID used as
part of a message exchange pattern, I wonder why it isn't a URL. I think
ids in headers have a tendancy to hide shared communication state
instead of making it explicit. In this case I would prefer that the ID
be the URL of the resource that the client needs to interact with next.
When the client makes its request to the factory this urls should be
returned in the Location header of the response.

> Another thought I had was that the client could probably create the  
> ID itself (e.g. a tag: URI) and a new HTTP return code could indicate  
> to the client that the ID was't suitable (together with a good one in  
> the payload).

Mark Baker has just suggested the use of a client-generated id,
something like a client etag. The WS-* reliabile messaging specification
also uses a client-generated ID, but this time it is a sequence number
a-la TCP so that missed messages and message ordering can also be dealt
with.

I think the WS-* approach is interesting. I sometimes find myself
wanting to be sure that requests are processed in the order in which
they are sent. For example in SENA[1] I get a timing signal from the
server to indicate something has changed. If these signals arrive too
fast I might still have a previous GET outstanding. Should I send the
new GET immediately, or wait until the existing one returns?

If I send immediately the response will come back sooner, and I will be
able to update the state of some soft-realtime data on my page. However
under extreme conditions it is possible that my GET requests to the same
URL could be processed out of order. It might even be possible for the
response I recieve second to be older than the response I recieve first.
If I update the user's screen with the second I could be misleading
them.

In practice, however, the use of sequence numbers can be pretty limiting
to scalability. The REST constraint of "no shared communication state
between requests" helps explain why. If I am up to sequence number 200
and the server fails over to an unrelated server, we won't be able to
continue the conversation. We will have to reinitiate it from scratch.
This already happens with HTTP/1.1 TCP/IP connections. It is usually
necessary to tear down and reestablish the TCP/IP connection on server
failover. It is probably impractical to try and ensure TCP-level
failover even within a close-knit cluster. It is only slightly more
practical to use a TCP-like technique at the coarser-grained message
level. Certainly when clusters operate between physical sites it can
become quite difficult.

This suggests that reliable messaging that guarantees ordering of
message processing is not achievable in the general case, though special
environments may support it. There will always be chances for loss of
communication state on failover. Even without failover it is an unfair
assumption that a server will process requests from a single client in
sequence. Proxies could reorder or alter the sequence, and simple
threading models that perform parallelisation of processing will break
the model. Ultimately, at most once delivery is probably as close to the
ideal that we can reach in general.

On Sat, 2007-02-03 at 23:24 -0500, Mark Baker wrote:
> A technique I've used once was to have the client send an HTTP header
> in the POST request which played a role sort of like a client-side
> etag with respect to the request body.  The server, upon receiving the
> message and updating the state of the resource, would return another
> header containing a hash of the last days worth of tags (which wasn't
> many) on GET requests to that resource so that it could check if *its*
> update was applied.

The SCADA approach is more direct, but then again it is working on
physical devices. You send a request for a transition. If all of the
computer and networking devices are fine you'll get the equivalent of an
OK back. However, all we know is that we kicked the servos into action.
It is possible that the mechanical device itself hasn't moved. The
device provides a read-back as to its actual state, and we configure a
timeout by which it must reach that state. No resends occur as this is
usually considered dangerous, however if the state doesn't match what we
requested soon enough it is reported as an error to the user for
correction.

The possible unreliability of mechanical devices (even of their
read-backs) has interesting effects on idempotency. We have what are
known as "trip to trip" transitions and "close to close". In other
words, everything we can see says that the device is in a particular
state. However the user has determined from other evidence (ie by
examining other resources) that we are being lied to. They send a
request to put the device into the same state that it is currently in.
We give the servos on the device another kick, and it usually fixes the
problem. Interestingly, though, we would normally not retry an
idempotent request like this automatically. Every time we kick those
servos it reduces the lifetime of the mechanical device. A big circuit
breaker might only have 50 trips in it before it needs maintenence. We
would not normally issue any request to a device like that unless the
user is directly at the helm requesting it.

Benjamin.
[1] http://soundadvice.id.au/blog/draft-carlyle-sena-01.txt

On 04.02.2007, at 09:55, Benjamin Carlyle wrote:

> On Sat, 2007-01-27 at 11:32 +0100, Jan Algermissen wrote:
>> The model I am thinking about to achieve POE is based on the use of
>> Atom and the inclusion of an ID in the POST body (or an HTTP header).
>> POE aware clients would receive the ID to use from a factory, non-POE
>> aware clients would just do the normal POST.
>
> One of my REST design instincts is that whenever I see an ID used as
> part of a message exchange pattern, I wonder why it isn't a URL. I  
> think
> ids in headers have a tendancy to hide shared communication state
> instead of making it explicit. In this case I would prefer that the ID
> be the URL of the resource that the client needs to interact with  
> next.
> When the client makes its request to the factory this urls should be
> returned in the Location header of the response.

Yes, exactly. Currently I am thinking about

POST /poe-collection-factory

201 Created
Location: /peo-collections/66525

Meaning the client requests the factory to create a poe collection  
(an APP collection that supports POST-retry)


>
>> Another thought I had was that the client could probably create the
>> ID itself (e.g. a tag: URI) and a new HTTP return code could indicate
>> to the client that the ID was't suitable (together with a good one in
>> the payload).
>
> Mark Baker has just suggested the use of a client-generated id,
> something like a client etag. The WS-* reliabile messaging  
> specification
> also uses a client-generated ID, but this time it is a sequence number
> a-la TCP so that missed messages and message ordering can also be  
> dealt
> with.

Yes, interesting. Have to think about it. Generally what I dislike  
about all ideas so far is the
server side state, even if it is cheap. It sill affects scalability,  
runtime substitution of server components etc., basically
all the good stuff about REST we tend to promote :-)

>
> I think the WS-* approach is interesting. I sometimes find myself
> wanting to be sure that requests are processed in the order in which
> they are sent. For example in SENA[1] I get a timing signal from the
> server to indicate something has changed. If these signals arrive too
> fast I might still have a previous GET outstanding. Should I send the
> new GET immediately, or wait until the existing one returns?
>
> If I send immediately the response will come back sooner, and I  
> will be
> able to update the state of some soft-realtime data on my page.  
> However
> under extreme conditions it is possible that my GET requests to the  
> same
> URL could be processed out of order. It might even be possible for the
> response I recieve second to be older than the response I recieve  
> first.
> If I update the user's screen with the second I could be misleading
> them.
>
> In practice, however, the use of sequence numbers can be pretty  
> limiting
> to scalability. The REST constraint of "no shared communication state
> between requests" helps explain why. If I am up to sequence number 200
> and the server fails over to an unrelated server, we won't be able to
> continue the conversation. We will have to reinitiate it from scratch.
> This already happens with HTTP/1.1 TCP/IP connections. It is usually
> necessary to tear down and reestablish the TCP/IP connection on server
> failover. It is probably impractical to try and ensure TCP-level
> failover even within a close-knit cluster. It is only slightly more
> practical to use a TCP-like technique at the coarser-grained message
> level. Certainly when clusters operate between physical sites it can
> become quite difficult.

Only scanned these paragraphs quickly, but it appears there is something
communication state that should be represented as a resource, or?


>
> This suggests that reliable messaging that guarantees ordering of
> message processing is not achievable in the general case, though  
> special
> environments may support it. There will always be chances for loss of
> communication state on failover. Even without failover it is an unfair
> assumption that a server will process requests from a single client in
> sequence.

IMO, if you want sequence, you need an application that controls that  
sequence
(via hypermedia).

Coordination between processes is on a request-by-request basis in  
REST. If you
want more complex coordination, you need application state (managed  
by some
of the coordinated parties).


> Proxies could reorder or alter the sequence, and simple
> threading models that perform parallelisation of processing will break
> the model. Ultimately, at most once delivery is probably as close  
> to the
> ideal that we can reach in general.
>
> On Sat, 2007-02-03 at 23:24 -0500, Mark Baker wrote:
>> A technique I've used once was to have the client send an HTTP header
>> in the POST request which played a role sort of like a client-side
>> etag with respect to the request body.  The server, upon receiving  
>> the
>> message and updating the state of the resource, would return another
>> header containing a hash of the last days worth of tags (which wasn't
>> many) on GET requests to that resource so that it could check if  
>> *its*
>> update was applied.
>
> The SCADA approach is more direct, but then again it is working on
> physical devices. You send a request for a transition. If all of the
> computer and networking devices are fine you'll get the equivalent  
> of an
> OK back. However, all we know is that we kicked the servos into  
> action.
> It is possible that the mechanical device itself hasn't moved. The
> device provides a read-back as to its actual state, and we configure a
> timeout by which it must reach that state. No resends occur as this is
> usually considered dangerous, however if the state doesn't match  
> what we
> requested soon enough it is reported as an error to the user for
> correction.
>
> The possible unreliability of mechanical devices (even of their
> read-backs) has interesting effects on idempotency. We have what are
> known as "trip to trip" transitions and "close to close". In other
> words, everything we can see says that the device is in a particular
> state. However the user has determined from other evidence (ie by
> examining other resources) that we are being lied to. They send a
> request to put the device into the same state that it is currently in.
> We give the servos on the device another kick, and it usually fixes  
> the
> problem. Interestingly, though, we would normally not retry an
> idempotent request like this automatically. Every time we kick those
> servos it reduces the lifetime of the mechanical device. A big circuit
> breaker might only have 50 trips in it before it needs maintenence. We
> would not normally issue any request to a device like that unless the
> user is directly at the helm requesting it.
>

Unable to digest all this right now, but sounds very interesting.

Jan

> Benjamin.
> [1] http://soundadvice.id.au/blog/draft-carlyle-sena-01.txt
>

On 04.02.2007, at 05:24, Mark Baker wrote:

> On 2/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
>> So here are the strategies I can think of seeing so far:
>> 1. Have the user observe some property of the system to determine
>> whether to retry themselves. [...]
>
> [...]
> A technique I've used once was to have the client send an HTTP header
> in the POST request which played a role sort of like a client-side
> etag with respect to the request body.  The server, upon receiving the
> message and updating the state of the resource, would return another
> header containing a hash of the last days worth of tags (which wasn't
> many) on GET requests to that resource so that it could check if *its*
> update was applied.

Yes, I was thinking about taking the POST-and-GET-to-check route instead
of a special interaction pattern. In the case of APP this would be  
even simpler,
as all I'd need to be looking for as a client is the existence of the  
POSTed entry
in the collection (though I'll have to do some more evaluation of how  
to actually
check for identity[1]..ETag, Atom ID,...)

One problem of this I see is laency. When could the client expect  
that its POST
did not came through if it does not see the intended effect? What if  
the POST response
(the one id did not receive) was 202 as opposed to 201?

Jan

[1] Mark, how did you ensure Client-ETag uniqueness across clients?



>
> Interesting post...
>
> Mark.
> -- 
> Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
> Coactus; Web-inspired integration strategies  http://www.coactus.com
>
>
>
> Yahoo! Groups Links
>
>
>

> > "The requested resource is no longer available at the server and no
> > forwarding address is known. This condition is expected to be
> > considered permanent." - rfc2616
>
> OK, fair point. It does however raise the question: "What should
> happen if a PUT is made to a resource where it is known that it will
> never exist again?"

It's expected that it will not exist again, not guaranteed. Certainly if it's
deemed very likely that something will be PUT there again it should be a 404
rather than a 410, but it's not erroneous for something to be PUT to a URI
currently resulting in 410.

The important consequence of this is that while recieving a 410 should result in
any recorded information about a URI held other than on the server being
deleted*, it should not be assumed that a reference to that URI found elsewhere
is outdated as it could exist because of something PUT there (or merely put
there by other means) later. So we should delete any such records, but not
record them in any permanent "known to not exist" record.


*Caches being the most obvious example, but 404s would also delete that data in
most cases (some specialised caches of information, rather than pure web
caches, may not) - a more interesting example would be a search engine's
records for both search results and future spidering, a 404 could be a
temporary and erroneous condition so that URI should be respidered later, but a
410 should drop the record from the respidering list - incidentally google seems
to do this.

-- 
Jon Hanna
<http://www.hackcraft.net/>
"�if it walks like a duck, and quacks like a duck, it's probably not a
ConceptualWork about a duck." - Mark Baker

(resending this to the list, sorry for the dupe, Mark)

Am 02.02.2007 um 13:30 schrieb Mark Baker:
> Ok, but you needn't use text/uri-list.   text/html would work as well
> (with lots more content, of course).  The point is simply that you can
> treat the die/dice as a random data source and therefore a vanilla
> GET/200 exchange should suffice.

Yes :)

But what's the advantage here? I'm probably not seeing it.

I understand that this has the advantage of decoupeling things even  
further than a 302 Found response does in that it (the 200 Ok text/ 
uri-list) leaves the decision of calling the URI (or doing whatever  
else with it) completely to the client.

So, I could see how I would want to use this approach in an (say)  
AJAX-based application. But, as I'm planning to go with plain HTML,  
the usual browsers etc. ... how would I use this?


> On 2/2/07, Sven Fuchs <svenfuchs@artweb-design.de> wrote:
>> Am 01.02.2007 um 19:56 schrieb Mark Baker:
>>> How about;
>>> GET /trainer
>>> ->
>>> 200 Ok
>>> Content-Type: text/uri-list
>>> http://example.org/activity/9
>>
>> Cool :)
>>
>> I've not been aware of this content-type. I (think I) understand how
>> this kind of response exactly models what I've been asking for.
>>
>> But as I'm going to implement this as a web application (using a
>> browser as a client) I right now think that a 302 Found/Location
>> redirect should do it.
>>
>> --
>> sven fuchs                      fon:  +49 (58 45) 98 89 58
>> artweb design                   fax:  +49 (58 45) 98 89 57
>> breite stra�e 65                www: http://www.artweb-design.de
>> de-29468 bergen         mail: svenfuchs@artweb-design.de
>>
>>
>>
>>
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>
>
> -- 
> Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
> Coactus; Web-inspired integration strategies  http://www.coactus.com
>
>
>
> Yahoo! Groups Links
>
>
>

-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@...

(resending this to the list, sorry for the dupe, Benjamin)

Am 03.02.2007 um 22:46 schrieb Benjamin Carlyle:
> You have mentioned that in its simplest form this is throwing a die,
> however there seem to be more complex forms involved as well. The
> trainer may have to consider what has already been completed in  
> order to
> make an appropriate decision.

Yes. :)

I've just tried to reduce the question to the minimum at this point.

But of course you're right. The more complex behaviour of the trainer  
might even be pretty much predictable when one knows the exact  
algorithm hidden here, but at the same time might appear to be  
completely random to a user looking from the outside. As far as I  
understand REST deals with what is visible from the outside.

> That means that the list of what has been
> completed has to be included explicitly or implicitly in the url.
>
> Explicitly (client keeps track of which are completed):
> http://example.com/thetrainer?completed=1+2+3+4
>
> Implicitly (server keeps track of which are completed):
> http://example.com/thetrainer?student=foo
> (add authentication details here?)
>
> In the client-side case you would likely need to be rewriting hrefs in
> pages your return to the student to include the list of completed  
> items.
> In the server-side case you would likely need the client to PUT or  
> POST
> information about completed courses, possibly in the form of completed
> exam papers for example.

Yes, absolutely.

I've started implementing this having the server keeping track of the  
state.

-- 
sven fuchs			fon:  +49 (58 45) 98 89 58
artweb design			fax:  +49 (58 45) 98 89 57
breite stra�e 65		www: http://www.artweb-design.de
de-29468 bergen		mail: svenfuchs@...

On Sun, Feb 04, 2007 at 10:55:43AM +1000, Benjamin Carlyle wrote:
> My suggestion is to use a resource that allows them to do everything
> they want as one operation. Without a more detailed explaination of what
> the customer might be doing it is hard to be specific, but let's look at
> an example where they want to publish a thousand atom articles:
(snip)

That's fine and dandy, but I'm more concerned about the example where
they want to publish ten thousand atom media entities.

(snip)
> You can use a POE technique to ensure that this operation can be safely
> retried if the client recieves no response.

What is POE?

> In my opinion, online services of all kinds (From REST to WS-*) will
> tend to perform, scale and behave better when a single request is a
> single request. Once the request is received, it is the responsbility of
> the service that recieves the request to ensure it is treated as an
> atomic update.

Noted. Many of our requirements fit perfectly into the single-request
model. It's just the bulk loading stuff that's a pain.
Maybe I should provide as separate interface for that.

-- 

Paul Winkler
http://www.slinkp.com

Paul Winkler <pw_lists@...> writes:

> Noted. Many of our requirements fit perfectly into the single-request
> model. It's just the bulk loading stuff that's a pain.
> Maybe I should provide as separate interface for that.

Is it though? Surely you could publish a format requirement for a
POSTed entity that allowed bulk uploading in one shot.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Mon, Feb 05, 2007 at 06:54:20PM +0000, Nic James Ferrier wrote:
> Paul Winkler <pw_lists@...> writes:
> 
> > Noted. Many of our requirements fit perfectly into the single-request
> > model. It's just the bulk loading stuff that's a pain.
> > Maybe I should provide as separate interface for that.
> 
> Is it though? Surely you could publish a format requirement for a
> POSTed entity that allowed bulk uploading in one shot.

Sure, but that's impractical when I have gigabytes of stuff to load in
one "transaction", as mentioned previously in the thread.

-- 

Paul Winkler
http://www.slinkp.com

Paul Winkler <pw_lists@...> writes:

> On Mon, Feb 05, 2007 at 06:54:20PM +0000, Nic James Ferrier wrote:
>> Paul Winkler <pw_lists@...> writes:
>> 
>> > Noted. Many of our requirements fit perfectly into the single-request
>> > model. It's just the bulk loading stuff that's a pain.
>> > Maybe I should provide as separate interface for that.
>> 
>> Is it though? Surely you could publish a format requirement for a
>> POSTed entity that allowed bulk uploading in one shot.
>
> Sure, but that's impractical when I have gigabytes of stuff to load in
> one "transaction", as mentioned previously in the thread.

Ok. But if you can't load it in a single request then....


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On 2/4/07, Sven Fuchs <svenfuchs@...> wrote:
> Am 02.02.2007 um 13:30 schrieb Mark Baker:
> > Ok, but you needn't use text/uri-list.   text/html would work as well
> > (with lots more content, of course).  The point is simply that you can
> > treat the die/dice as a random data source and therefore a vanilla
> > GET/200 exchange should suffice.
>
> Yes :)
>
> But what's the advantage here? I'm probably not seeing it.
>
> I understand that this has the advantage of decoupeling things even
> further than a 302 Found response does in that it (the 200 Ok text/
> uri-list) leaves the decision of calling the URI (or doing whatever
> else with it) completely to the client.

It's more that the client doesn't request the roll as it does with the
other approaches; it simply makes observations of the state of the
dice on the server.

> So, I could see how I would want to use this approach in an (say)
> AJAX-based application. But, as I'm planning to go with plain HTML,
> the usual browsers etc. ... how would I use this?

Like this, only with more HTML, and (as I understand your needs), the
random value would be turned into a link;

http://www.random.org/cgi-bin/randnum?num=1&min=1&max=6

Mark.

On 2/4/07, Jan Algermissen <algermissen1971@...> wrote:
>
> On 04.02.2007, at 05:24, Mark Baker wrote:
>
> > On 2/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> >> So here are the strategies I can think of seeing so far:
> >> 1. Have the user observe some property of the system to determine
> >> whether to retry themselves. [...]
> >
> > [...]
> > A technique I've used once was to have the client send an HTTP header
> > in the POST request which played a role sort of like a client-side
> > etag with respect to the request body.  The server, upon receiving the
> > message and updating the state of the resource, would return another
> > header containing a hash of the last days worth of tags (which wasn't
> > many) on GET requests to that resource so that it could check if *its*
> > update was applied.
>
> Yes, I was thinking about taking the POST-and-GET-to-check route instead
> of a special interaction pattern. In the case of APP this would be
> even simpler,
> as all I'd need to be looking for as a client is the existence of the
> POSTed entry
> in the collection (though I'll have to do some more evaluation of how
> to actually
> check for identity[1]..ETag, Atom ID,...)

But that would be an implementation dependency, so your client
wouldn't be reusable with, say, non-APP resources.  My approach is
generic.

>
> One problem of this I see is laency. When could the client expect
> that its POST
> did not came through if it does not see the intended effect? What if
> the POST response
> (the one id did not receive) was 202 as opposed to 201?

Then it would have to keep checking or else a subscription would have
to be made.

>
> Jan
>
> [1] Mark, how did you ensure Client-ETag uniqueness across clients?

IIRC, it was something like a MIME Message-Id.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On Mon, 2007-02-05 at 10:25 -0500, Paul Winkler wrote: 
> On Sun, Feb 04, 2007 at 10:55:43AM +1000, Benjamin Carlyle wrote:
> > You can use a POE technique to ensure that this operation can be
> safely
> > retried if the client recieves no response.
> What is POE?

Sorry: Post Once Exactly. Techniques for this are currently being
discussed in the POST at most once thread.

> On Mon, 2007-02-05 at 14:05 -0500, Paul Winkler wrote:
> On Mon, Feb 05, 2007 at 06:54:20PM +0000, Nic James Ferrier wrote:
> > Paul Winkler <pw_lists@...> writes:
> > > Noted. Many of our requirements fit perfectly into the
> single-request
> > > model. It's just the bulk loading stuff that's a pain.
> > > Maybe I should provide as separate interface for that.
> > Is it though? Surely you could publish a format requirement for a
> > POSTed entity that allowed bulk uploading in one shot.
> Sure, but that's impractical when I have gigabytes of stuff to load in
> one "transaction", as mentioned previously in the thread.

That would seem to be a problem with implementation technology, however
I conceed that such limitations need to be worked around :)

So let's look at this in stages:
1. Transfer state of new publications to server
2. Server acts on the publication as an atomic unit
3. Client is notified of transaction completion

The simplest implementation of POST -> 200 OK is not available because
the implementation technology would cause us to eat up all available
memory just transferring the request. So we use

1a. Use any available file transfer mechanism from client to server
1b. Request the server use the transferred file as input
2. Server acts on publication as an atomic unit
3. Server replies with 200 OK, or sends a request back to the client
saying effectively 200 OK.

This leaves us with a number of problems still to solve. For example,
how do we phrase the "load this data" request. It is most analagous to
the WebDav COPY request. ie, copy the file resource we just gave you to
the set of published nodes. You'll find varying opinions on the merit of
COPY on this list. IIRC Fielding has noted in the past that HTTP is
designed to operate on a single url, and that WebDav COPY and related
operations have both theoretical and practical problems attached to
them.

The other alternative is to head in the direction you are already
heading, which is unlikely to be worse than the file transfer + COPY
approach. Perform the transaction piecemeal with POSTs to a transaction
url or other requests that refer to the transaction url in a header,
then POST a commit marker into the transaction resource.

If the client really needs to make the update atomically and your
implementation technology really doesn't permit the update to be
performed as a single request, you have to head in this sort of
direction. Just plan your error recovery carefully. There are a lot more
ways that multiple requests can go wrong.

Benjamin.

On Wed, Feb 07, 2007 at 07:24:18AM +1000, Benjamin Carlyle wrote:
> .... Just plan your error recovery carefully. There are a lot more
> ways that multiple requests can go wrong.

Indeed! Thanks very much for the tips.

-- 

Paul Winkler
http://www.slinkp.com

Chris Dent wrote:
> I wonder if it would also be useful to 
> implement .<filetype extension>?

Just curious what specifically you were thinking...


-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

Bill Venners wrote:
> Perhaps I misunderstood you. I agree with your aesthetic 
> sense that paths are prettier than queries in URIs. But I 
> think that both path and queries are needed, so sometimes you 
> will have query parts. The question I was asking is which 
> form of embedding query params in URIs might they be the most 
> pretty and user friendly?
> 
> http://www.artima.com/articles?o=a&t=java&p=7
> 
> Is the traditional way. But:
> 
> http://www.artima.com/articles;a,tjava,p7
> 
> or
> 
> http://www.artima.com/articles~a,tjava,p7
> 
> Could also be used in our architecture. I'm not sure that 
> they are much prettier than the traditional query form, but 
> the latter forms are shorter.

Can you give some use cases where queries are *needed* (beyond one query
parameter?)  

I'm not disagreeing, just wanting to see your use cases.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

"Mike Schinkel" <mikeschinkel@...> writes:

> Can you give some use cases where queries are *needed* (beyond one query
> parameter?)

For unstructured search (like google's basic search), you pretty much gives only one kind of input.

For structured search (like google's advance search), you need to
'type' each input. For example, if I supply "2006-10-20", I want to
type it as the modification date, instead of a string somewhere in the
body of a page.


YS.

On Sat, 2007-02-03 at 23:24 -0500, Mark Baker wrote:
> On 2/3/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> > So here are the strategies I can think of seeing so far:
> > 1. Have the user observe some property of the system to determine
> > whether to retry themselves. In SCADA this might be to observe a
> change
> > in voltage before deciding whether or not to retry a circuit-breaker
> > trip. This can be automated as another SCADA concept: "Target state
> > monitoring". Regardless of the reponse we recieved, did the resource
> > actually reach the state we intended?
> A technique I've used once was to have the client send an HTTP header
> in the POST request which played a role sort of like a client-side
> etag with respect to the request body. The server, upon receiving the
> message and updating the state of the resource, would return another
> header containing a hash of the last days worth of tags (which wasn't
> many) on GET requests to that resource so that it could check if *its*
> update was applied.

I'm starting to like this approach. Let me have a go at rephrasing it as
a concrete proposal:

Problem statement: (same as before)
I have some state that I want to append to a resource. The right method
according to HTTP is POST, but if I don't get a response to my POST I
don't know whether or not to retry.

Client algorithm:
...
guid = generateGloballyUniqueID();
request.addHeader("Client-Etag",guid);
try
{
retryPOST:
    startOrResetTimer(reasonable digest retention period, eg 2min);
    factory.POST(request);
}
catch (NoResponse) // aka GatewayTimeout
{
    etagDigest = factory.GET();
    if (guid in etagDigest)
    {
        // Nothing to be done. The POST was successful.
    }
    else
    {
        // One of two possibilities exist. Either,
        // * our POST didn't arrive, or
        // * our etag has cycled out of the digest
        // We try to ensure that the latter doesn't
        // happen by giving up after a reasonable
        // period.
        goto retryPOST;
    }
}
catch (RetentionPeriodTimeout)
{
    // It is still possible that our etag would be in
    // the digest at this point, so we could do a final
    // GET. If we are in the digest, there is no problem.
    // If we are not in the digest we can no longer assume
    // that it is because our request didn't happen.
    // Our request might have simply cycled out.
}
catch (...)
{
    // Normal error handling
}

Server constraints:
* Client etags are stored in the factory as a digest of recent POST
requests for a reasonable amount of time
* Only successful requests have their etag stored in the digest, so
clients can still retry failed requests. Success would generally mean
that state was successfully appended to the server, though there may be
some corner cases.

Possible efficiency improvements:
* A URI template might allow the client to query for their specific
etag, but a protocol would have to be developed for this. Perhaps
instead of a digest, the factory could return this template. That would
also potentially deal with security issues arising from guids leaking
from one client to another.

Pros/Cons:
* In the normal case where the POST does not time out there is very
little extra communications overhead
* The server has to store the state of recent successful requests for a
period rather than the state of requests that did not go ahead. ie we
trade less communications overhead for more server state overhead. On
the other hand, this server state overhead should be proportional to the
amount of state the server allowed to be appended to itself as part of
the POST. It doesn't change the fundamental server-side state picture...
just changes the constant.

Cautions
* Under extreme conditions there could still be a race condition between
a POST arriving at the server and a GET request being issued to the
factory or template-derived url. This shouldn't really happen if the
client gives up on the POST under reasonable conditions. Those might
include "40s has passed", or "I'm using TCP/IP keepalive while requests
are outstanding to monitor our shared communication state, and the HA
cluster member I was talking to appears to have been replaced by its
backup, killing my connection". The final case of "I'm using TCP/IP
keepalive while requests are outstanding, and it simply timed out due to
network conditions" could still be a problem.

Benjamin

Yohanes Santoso wrote:
> > Can you give some use cases where queries are *needed* (beyond one 
> > query
> > parameter?)
> 
> For unstructured search (like google's basic search), you 
> pretty much gives only one kind of input.
> 
> For structured search (like google's advance search), you 
> need to 'type' each input. For example, if I supply 
> "2006-10-20", I want to type it as the modification date, 
> instead of a string somewhere in the body of a page.

Ah.   

BTW, and this is a philosophy point, encoding into a single string for a
search query IMO is probably the better way to go because then it is
resilient to change.  Splitting out into different parameters means the
interface might need to change when you add new features.  This is
essentially the same argument for why the URL as a single string is better
than an EPR[1].

Also, could you not encode date into the URL path?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

[1]
http://lists.w3.org/Archives/Public/www-tag/2006Dec/att-0038/EnterpriseWSTag
.html

I'm building an internal system here at work and while I've been able
for the most part to model a RESTful interface for it, there's one
thing that I haven't been able to model quite successfully: batch
updates of resources.

I wouldn't be revealing too much to say that the system acts as a
single interface around the repository manipulation systems of the
various domain registrars we use, one of which is the IEDR, the Irish
Domain Registry. The IEDR, as with many other domain registries, use
EPP[1] or a variant thereof to allow resellers to manipulate their
repositories. The IEDR's own implementation extends EPP to implement
their MSD process. The MSD process allows resellers to suspend a
domain as a credit control measure for about 30 days. If a domain
which is in the MSD process is not taken out of it and unsuspended by
the time, the domain becomes available for registration again.

The problem here is that on any given day, a large number of domains
can be moved in and out of the MSD process, and this is generally done
in batches.

Currently, the cleanest way I can think of is to POST a collection of
domain representations to a special 'batch' endpoint, not entirely
unlike the way that GData works. But that doesn't feel quite right,
almost as if I'm abusing POST.

Has anybody else ever encountered a similar problem to this, and if
so, how did you go about solving it.

K.

[1] http://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol
    Take a read of the RFCs: it's like staring into hell.

Keith Gaughan wrote:
> Currently, the cleanest way I can think of is to POST a collection of
> domain representations to a special 'batch' endpoint, not entirely
> unlike the way that GData works. But that doesn't feel quite right,
> almost as if I'm abusing POST.

Collection is a type of resource once you take an "everything is a 
resource" view.

Representation of a collection is therefore a valid thing to POST.

As such it doesn't seem like abusing POST to POST a representation of a 
collection to a resource that handles such collections. Quite the 
obvious approach in fact.

Now, if it makes good conceptual sense to identify that batch with its 
own batch identifier (by which I mean, it makes sense within your model 
to do so, particularly if you might want to retrieve information about 
that batch at a later date) AND if it makes good sense for the client to 
determine the identifier, then you've got something where PUT also makes 
sense and is probably actually better.

Otherwise I'd POST.

On Thu, 2007-02-08 at 17:17 +0000, Keith Gaughan wrote:
> The problem here is that on any given day, a large number of domains
> can be moved in and out of the MSD process, and this is generally done
> in batches.
> Currently, the cleanest way I can think of is to POST a collection of
> domain representations to a special 'batch' endpoint, not entirely
> unlike the way that GData works. But that doesn't feel quite right,
> almost as if I'm abusing POST.

My simple rule of thumb is this:
* If you are replacing information, you are PUTting
* If you are adding information, you are POSTing
* If you are removing information, you are DELETE-ing
* If you are retrieving information, you are GETting

So now the question becomes: What is the url of the information you are
replacing, adding, removing, or retrieving?

For batch jobs determining this url can be hard. If you are finding it
hard, perhaps REST is not the right tool for the job here... or perhaps
you have couched the problem in terms that made sense for a non-REST
system that now need to be rethought.

For example, why are you doing these things in batches? Could your
clients pipeline requests instead and transfer the same requests in the
same amount of time as a batch request? Could they simply retry requests
they didn't get a response on, instead of unnecessarily treating the
batch like a transaction?

Benjamin.

On 1/27/07, Bill de hOra <bill@...> wrote:
>  The problem in my mind GET a cached ID and sharing it with someone else.
>  If you want to serve IDs have clients use POST.

Correct.

If you're trying to solve this problem in a browser where
only GET and POST are allowed then you can use that POST to
create a new ID that is used in a subsequent POST.

If you are outside HTML forms then since you're POSTing
you mine as well create a new resource and return that via
201 and the Location: header. The client can then PUT a
representation to that newly created resource, and since PUT
is idempotent it can keep trying until it succeeds.

   -joe

-- 
Joe Gregorio        http://bitworking.org

On 2/7/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
> I'm starting to like this approach. Let me have a go at rephrasing it as
> a concrete proposal:
>
> Problem statement: (same as before)
> I have some state that I want to append to a resource. The right method
> according to HTTP is POST, but if I don't get a response to my POST I
> don't know whether or not to retry.

I'm not sure what you mean by "append", but this approach is useful
for both POST(a) as well as POST(p).

>
> Client algorithm:
> ...
> guid = generateGloballyUniqueID();

That would be more of a message id, which is ok if you just want
verifiable once-and-only-once.  But you also have the option of making
the tag value a function of the request representation, which would be
useful in cases where the same representation might be sent in
multiple messages.

Your analysis looks pretty good.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

It had to happen sooner or later. The big boys are waking up and 
discovering REST, and naturally they want to protect all us little 
developers from worrying our pretty little heads about nasty things like 
HTTP and XML by creating easy-to-use REST frameworks:

JSR-311 Java API for RESTful Web Services
http://jcp.org/en/jsr/detail?id=311

Remember, these are the same jokers who gave us servlets and the 
URLConnection class as well as gems like JAX-RPC and JAX-WS. They still 
seem to believe that these are actually good specs, and they are 
proposing to tunnel REST services through JAX-WS (Java API for XML Web 
Services) endpoints.

They also seem to believe that "building RESTful Web services using the 
Java Platform is significantly more complex than building SOAP-based 
services". I don't know that this is false, but  if it's true it's only 
because Sun's HTTP API were designed by architecture astronauts who 
didn't actually understand HTTP. This proposal does not seem to be 
addressing the need for a decent HTTP API on either the client or server 
side that actually follows RESTful principles instead of fighting 
against them.

To give you an idea of the background we're dealing with here, one of 
the two people who wrote the proposal "represents Sun on the W3C XML 
Protocol and W3C WS-Addressing working groups where he is co-editor of 
the SOAP 1.2 and WS-Addressing 1.0 specifications. Marc was 
co-specification lead for JAX-WS 2.0 (the Java API for Web Services) 
developed at the JCP and has also served as Sun's technical lead and 
alternate board member at the Web Services Interoperability Organization 
(WS-I)."

The other submitter seems to be a primary instigator of the Fast Infoset 
effort to hide XML in binary goop.

This is like asking Karl Rove and Dick Cheney to write the Democratic 
Party platform.

Do we really want to trust these folks to define the official Java spec 
for REST? Please read the JSR, and send comments to jsr-311-comments@...

I hope we can derail this completely, but we probably can't. If not, are 
there any JSR members here who might join the working group and bring 
some sanity and actual REST experience to the development of the 
eventual specification? If we can't stop it, maybe we can at least limit 
the damage.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

I was about to write something similar...

In the first place I don't understand why this needs to be a JSR. I
understand JSR as a means to standardize something existent into the
Java platform. But there is no ecosystem of competing
software-that-lends-to-the-REST-architectural-style-TM in Java in the
first place. These guys should open a java.net project, gain some
popularity and come back in two years.

Alas, real damage will happen when someone tries to include this into
J2SE. JSRs as such do not necessarily mean too much.

Jerome Louvel is slated to go on the EG and - to my recollection - is
the only one who's building a REST-oriented framework in Java and who
I've seen active in this community. Jerome, maybe you can comment.

Will send similar comments to that address.

Thanks for bringing this up
Matthias

-- 
matthias.ernst@...
software architect
+49.40.32 55 87.503
 

> -----Original Message-----
> From: rest-discuss@yahoogroups.com 
> [mailto:rest-discuss@yahoogroups.com] On Behalf Of Elliotte Harold
> Sent: Wednesday, February 14, 2007 3:56 PM
> To: REST Discuss
> Subject: [rest-discuss] Sun proposes to apply Web service 
> standardization principles to REST
> 
> It had to happen sooner or later. The big boys are waking up and 
> discovering REST, and naturally they want to protect all us little 
> developers from worrying our pretty little heads about nasty 
> things like 
> HTTP and XML by creating easy-to-use REST frameworks:
> 
> JSR-311 Java API for RESTful Web Services
> http://jcp.org/en/jsr/detail?id=311
> 
> Remember, these are the same jokers who gave us servlets and the 
> URLConnection class as well as gems like JAX-RPC and JAX-WS. 
> They still 
> seem to believe that these are actually good specs, and they are 
> proposing to tunnel REST services through JAX-WS (Java API 
> for XML Web 
> Services) endpoints.
> 
> They also seem to believe that "building RESTful Web services 
> using the 
> Java Platform is significantly more complex than building SOAP-based 
> services". I don't know that this is false, but  if it's true 
> it's only 
> because Sun's HTTP API were designed by architecture astronauts who 
> didn't actually understand HTTP. This proposal does not seem to be 
> addressing the need for a decent HTTP API on either the 
> client or server 
> side that actually follows RESTful principles instead of fighting 
> against them.
> 
> To give you an idea of the background we're dealing with here, one of 
> the two people who wrote the proposal "represents Sun on the W3C XML 
> Protocol and W3C WS-Addressing working groups where he is 
> co-editor of 
> the SOAP 1.2 and WS-Addressing 1.0 specifications. Marc was 
> co-specification lead for JAX-WS 2.0 (the Java API for Web Services) 
> developed at the JCP and has also served as Sun's technical lead and 
> alternate board member at the Web Services Interoperability 
> Organization 
> (WS-I)."
> 
> The other submitter seems to be a primary instigator of the 
> Fast Infoset 
> effort to hide XML in binary goop.
> 
> This is like asking Karl Rove and Dick Cheney to write the Democratic 
> Party platform.
> 
> Do we really want to trust these folks to define the official 
> Java spec 
> for REST? Please read the JSR, and send comments to 
> jsr-311-comments@...
> 
> I hope we can derail this completely, but we probably can't. 
> If not, are 
> there any JSR members here who might join the working group and bring 
> some sanity and actual REST experience to the development of the 
> eventual specification? If we can't stop it, maybe we can at 
> least limit 
> the damage.

Elliotte,

It seems to me approaching the effort with this attitude is not going  
to lead to a productive debate :-)

RESTlet author J�r�me Louvel is also a member of the initial expert  
group, and while I have serious doubts about the code generation  
aspect, Marc Hadley's WADL seems to indicate he "gets" REST.

Regarding

On Feb 14, 2007, at 3:56 PM, Elliotte Harold wrote:
>
> I hope we can derail this completely, but we probably can't. If  
> not, are
> there any JSR members here who might join the working group and bring
> some sanity and actual REST experience to the development of the
> eventual specification? If we can't stop it, maybe we can at least  
> limit
> the damage.
I believe the JSR is the chance to get decent HTTP support into the  
JDK, so I'd strongly suggest influencing instead of stopping it.

Best regards,
Stefan

Hi Elliotte,

Let me look at this effort on a more constructively light. You forgot to 
mention that Marc Hadley is also the author of WADL which is the best 
RESTful description language available. He may have been involved in 
other standardization efforts, but that doesn't mean he doesn't get REST 
now: I know he does.

I was also invited to the initial expert group, as a founder of the 
Restlet framework (http://www.restlet.org). I would like to mention that 
this JSR aims to provide a standard set of annotations to facilitate the 
mapping between business objects and REST resources. The implementation 
could be supported by either Restlets, Servlets or JAX-WS (via the HTTP 
bindings). I expect the result of this JSR to be complimentary to the 
Restlet API, which hopefully looks RESTful enough to you.

Let's not waste this opportunity to properly standardize REST on Java. 
See my recent posts for more details on my opinion:
http://blog.noelios.com/2007/02/14/new-jsr-to-define-a-high-level-rest-api-for-java/
http://blog.noelios.com/2007/02/08/will-we-reconcile-rest-ws-and-soa/

Best regards,
Jerome Louvel

Jerome Louvel wrote:

> Let's not waste this opportunity to properly standardize REST on Java.


What would one have to do to join the eg?

cheers
Bill

Hi Bill,

You can apply for an Expert Group Nomination at:
http://www.jcp.org/en/jsr/egnom?id=311

Thanks,
Jerome

Elliotte Harold <elharo@...> writes:

> Do we really want to trust these folks to define the official Java spec 
> for REST? Please read the JSR, and send comments to jsr-311-comments@...
>
> I hope we can derail this completely, but we probably can't. If not, are 
> there any JSR members here who might join the working group and bring 
> some sanity and actual REST experience to the development of the 
> eventual specification? If we can't stop it, maybe we can at least limit 
> the damage.

This does seem a bit negative.

I'm not sure I like REST-toolkits either... but only because REST is
not a protocol or a platform, it's just a style. But what else to call
such things?

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On 2/14/07, Jerome Louvel <contact@...> wrote:
>
> Hi Elliotte,
>
> Let me look at this effort on a more constructively light. You forgot to
> mention that Marc Hadley is also the author of WADL which is the best
> RESTful description language available.

Which Roy and I have both pointed out (in effect) is an oxymoron...

> He may have been involved in
> other standardization efforts, but that doesn't mean he doesn't get REST
> now: I know he does.

I like Marc a lot.  We worked together at Sun, and he's just a very
pleasant fellow.  But I think he misunderstands important aspects of
REST and the Web, so I have some concern there.

Anyhow, rather than be critical of this effort, I've decided to submit
my application to join the EG.  Java definitely needs better APIs for
the Web.

I am concerned about the request (section 2) though; it goes on and on
about how existing APIs are too "low level" and require a lot of
knowledge of HTTP, which suggests to me that they're thinking of
hiding as much of HTTP as possible; an obvious "protocol independence"
bias there which will only lead to a crappy API.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

J�r�me Louvel wrote:
> 
> 
> Hi Bill,
> 
> You can apply for an Expert Group Nomination at:
> http://www.jcp.org/en/jsr/egnom?id=311 
> <http://www.jcp.org/en/jsr/egnom?id=311>

Thanks J�r�me. I've just submitted a nomination request.

cheers
Bill

I've exchanged emails with Marc Hadley, collected some reactions and  
published a news item here:

http://www.infoq.com/news/2007/02/jsr-311-java-rest-api

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

On Feb 14, 2007, at 7:29 PM, Bill de hOra wrote:
> J�r�me Louvel wrote:
> >
> >
> > Hi Bill,
> >
> > You can apply for an Expert Group Nomination at:
> > http://www.jcp.org/en/jsr/egnom?id=311
> > <http://www.jcp.org/en/jsr/egnom?id=311>
>
> Thanks J�r�me. I've just submitted a nomination request.
>
> cheers
> Bill
>
> 

I just did the same.

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

Does anybody know how the expert groups work? Is there a public
mailing list where non-expert-group-members can be heard, or does this
all take place on some private mailing list?

--Chuck

On 2/14/07, Stefan Tilkov <stefan.tilkov@...> wrote:
> On Feb 14, 2007, at 7:29 PM, Bill de hOra wrote:
> > J�r�me Louvel wrote:
> > >
> > >
> > > Hi Bill,
> > >
> > > You can apply for an Expert Group Nomination at:
> > > http://www.jcp.org/en/jsr/egnom?id=311
> > > <http://www.jcp.org/en/jsr/egnom?id=311>
> >
> > Thanks J�r�me. I've just submitted a nomination request.
> >
> > cheers
> > Bill
> >
> >
>
> I just did the same.
>
> Stefan
> --
> Stefan Tilkov, http://www.innoq.com/blog/st/
>
>
>
>

Last time I participated on one, it was all private.  There's a public
review period though.

On 2/14/07, Chuck Hinson <chuck.hinson@...> wrote:
> Does anybody know how the expert groups work? Is there a public
> mailing list where non-expert-group-members can be heard, or does this
> all take place on some private mailing list?

I think there may be some missunderstandings about the direction of this JSR, I just 
posted a blog entry that aims to clarify a couple of points:

http://weblogs.java.net/blog/mhadley/archive/2007/02/jsr_311_java_ap.html

Regards,
Marc.

--- In rest-discuss@yahoogroups.com, Elliotte Harold <elharo@...> wrote:
>
> It had to happen sooner or later. The big boys are waking up and 
> discovering REST, and naturally they want to protect all us little 
> developers from worrying our pretty little heads about nasty things like 
> HTTP and XML by creating easy-to-use REST frameworks:
> 
> JSR-311 Java API for RESTful Web Services
> http://jcp.org/en/jsr/detail?id=311
> 
> Remember, these are the same jokers who gave us servlets and the 
> URLConnection class as well as gems like JAX-RPC and JAX-WS. They still 
> seem to believe that these are actually good specs, and they are 
> proposing to tunnel REST services through JAX-WS (Java API for XML Web 
> Services) endpoints.
> 
> They also seem to believe that "building RESTful Web services using the 
> Java Platform is significantly more complex than building SOAP-based 
> services". I don't know that this is false, but  if it's true it's only 
> because Sun's HTTP API were designed by architecture astronauts who 
> didn't actually understand HTTP. This proposal does not seem to be 
> addressing the need for a decent HTTP API on either the client or server 
> side that actually follows RESTful principles instead of fighting 
> against them.
> 
> To give you an idea of the background we're dealing with here, one of 
> the two people who wrote the proposal "represents Sun on the W3C XML 
> Protocol and W3C WS-Addressing working groups where he is co-editor of 
> the SOAP 1.2 and WS-Addressing 1.0 specifications. Marc was 
> co-specification lead for JAX-WS 2.0 (the Java API for Web Services) 
> developed at the JCP and has also served as Sun's technical lead and 
> alternate board member at the Web Services Interoperability Organization 
> (WS-I)."
> 
> The other submitter seems to be a primary instigator of the Fast Infoset 
> effort to hide XML in binary goop.
> 
> This is like asking Karl Rove and Dick Cheney to write the Democratic 
> Party platform.
> 
> Do we really want to trust these folks to define the official Java spec 
> for REST? Please read the JSR, and send comments to jsr-311-comments@...
> 
> I hope we can derail this completely, but we probably can't. If not, are 
> there any JSR members here who might join the working group and bring 
> some sanity and actual REST experience to the development of the 
> eventual specification? If we can't stop it, maybe we can at least limit 
> the damage.
> 
> 
> -- 
> Elliotte Rusty Harold  elharo@...
> Java I/O 2nd Edition Just Published!
> http://www.cafeaulait.org/books/javaio2/
> http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/
>

Chuck Hinson wrote:
> Does anybody know how the expert groups work? Is there a public
> mailing list where non-expert-group-members can be heard, or does this
> all take place on some private mailing list?
> 

This is starting to change. A few are operating in public like JSR 305:

http://jcp.org/en/jsr/detail?id=305

Most are still private with limited public review. I do not know which 
approach 311 plans to take.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 14 Feb 2007, at 15:56, Elliotte Harold wrote:
> Do we really want to trust these folks to define the official Java  
> spec
> for REST? Please read the JSR, and send comments to jsr-311- 
> comments@...
You know, I think I trust Marc et all to come up with
something worthwhile and put it in the hands of a
lot of developers.

What worries me most about REST is that it isn't testable.
What allows you to say this site is "powered by REST"
beyond passing the sniff of a bunch of self-appointed
critics on this list.

In this respect it's really no better than SOA.

This kind of Email is one of the reasons why I tend to
avoid using the R-word.

Pirates. "Style". Pthrupt!

Paul
--
http://blog.whatfettle.com

Thanks,  Marc.  Good to get some light amidst the heat. :-)

Importantly, it doesn't really seem like they (you?) are trying to  
"standardize REST", but merely provide a "convenience API" for Java  
programmers who want to implement RESTful web services.  Right?

-enp
On Feb 14, 2007, at 1:34 PM, marc_hadley wrote:

> I think there may be some missunderstandings about the direction of  
> this JSR, I just
> posted a blog entry that aims to clarify a couple of points:
>
> http://weblogs.java.net/blog/mhadley/archive/2007/02/ 
> jsr_311_java_ap.html
>
> Regards,
> Marc.
>

On 2/14/07, Elliotte Harold <elharo@...> wrote:
>
> This is starting to change. A few are operating in public like JSR 305:
>
> http://jcp.org/en/jsr/detail?id=305
>
> Most are still private with limited public review. I do not know which
> approach 311 plans to take.

I hope that the discussion is public. I am a .NET developer, so a Java
implementation is not of primary interest to me, but I would certainly
be interested to track the thinking as it works through the API design
process to factor into my own.

I wonder what will be taken as the starting point.

Regards,
Alan Dean

On 2/14/07, Paul Downey <paul.downey@...> wrote:
>
> What worries me most about REST is that it isn't testable.
> What allows you to say this site is "powered by REST"
> beyond passing the sniff of a bunch of self-appointed
> critics on this list.
>
> In this respect it's really no better than SOA.

I am trying to tackle exactly this issue. I certainly agree that as a
general statement, REST isn't testable as it is an architectural style
... however ... I think that it is possible to make testable RESTful
patterns. There will be more than one pattern, to be sure, but each
pattern will be testable.

I am working on EARL test / assertion representations of my own
pattern and an engine to exercise EARL instances (hence the diagram I
showed the group last month). Having this would permit a web
application to claim a 'conformance level' to a specific pattern -
just as HTML can claim various WCAG conformance levels.

Alan Dean
http://thoughtpad.net/who/alan-dean/news

Paul Downey <paul.downey@...> writes:

> What worries me most about REST is that it isn't testable.
> What allows you to say this site is "powered by REST"
> beyond passing the sniff of a bunch of self-appointed
> critics on this list.

The reason you can't make REST testable is that REST isn't one
thing. It's an architectural style. HTTP allows highly RESTfull
systems. But an HTTP app can be more, or less, RESTfull.

However, it's impossible IMHO to talk about *pure* REST. Some things
RESTfull are in contradiction with others and the extent to which one
is used over another will be context specific. Some things
anti-RESTfull are perfectly acceptable to most developers and always
will be. Cookies are about to get another lease of life from openid
for example.


Having said that I think if there was enough interest one could make a
qualitative benchmarking system. I've dropped another post about that.


> This kind of Email is one of the reasons why I tend to
> avoid using the R-word.

And that would be quite right except when discussing the properties of
a particular web application/service as they pertain to it's
scalability and maintainability. Which is what we do here of course.

Roy has complained before about the term being hijacked. And I think
it is slightly dangerous to talk about RESTfull toolkits and REST
support. I am quite happy for people to say "this one thing is more
RESTfull than this other thing". As long as it is of course.



In conclusion I ask you this: is ML a functional language? Yes? Is ML
a pure functional language? Is C a functional language?

You take my point I'm sure: in the absence of another word REST is
going to be misused for implementation specifics.


> Pirates. "Style". Pthrupt!

Watch it. I'll have you down that plank before you can polish your
sabre.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

"Alan Dean" <alan.dean@...> writes:

> On 2/14/07, Paul Downey <paul.downey@...> wrote:
>>
>> What worries me most about REST is that it isn't testable.
>> What allows you to say this site is "powered by REST"
>> beyond passing the sniff of a bunch of self-appointed
>> critics on this list.
>>
>> In this respect it's really no better than SOA.
>
> I am trying to tackle exactly this issue. I certainly agree that as a
> general statement, REST isn't testable as it is an architectural style
> ... however ... I think that it is possible to make testable RESTful
> patterns. There will be more than one pattern, to be sure, but each
> pattern will be testable.
>
> I am working on EARL test / assertion representations of my own
> pattern and an engine to exercise EARL instances (hence the diagram I
> showed the group last month). Having this would permit a web
> application to claim a 'conformance level' to a specific pattern -
> just as HTML can claim various WCAG conformance levels.

Oh! that's excellent. Just the sort of thing I was thinking of.

Well done.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

So Paul would like to see something other than me going "aha! it's
like the pirate code me hearties" and other people going "eurgh" and
then there's an endless thread about pure or not so pure.

I think one could easily produce a series of qualitative tests for
HTTP based web services to establish their RESTfull goodness.

One would have to come up with a list of attributes of RESTfull
systems:

- what's the content types? 
- does it support HEAD properly? 
- what happens when you do methods that aren't supported? etc...

and then apply weights to each of them. 

Then write a client to test a webapp for each of the attributes (we
might call them constraints  /8-) and then produce a report.


Anyone interested in doing this with me?

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Feb 14, 2007, at 10:43 PM, Paul Downey wrote:

>
> On 14 Feb 2007, at 15:56, Elliotte Harold wrote:
> > Do we really want to trust these folks to define the official Java
> > spec
> > for REST? Please read the JSR, and send comments to jsr-311-
> > comments@...
> You know, I think I trust Marc et all to come up with
> something worthwhile and put it in the hands of a
> lot of developers.
>
> What worries me most about REST is that it isn't testable.
> What allows you to say this site is "powered by REST"
> beyond passing the sniff of a bunch of self-appointed
> critics on this list.
>
I agree ...
> In this respect it's really no better than SOA.
>
... and disagree. There is nothing even remotely close to a  
definitive work on SOA. This is different with REST - obviously,  
Roy's dissertation leaves room for interpretation, but it's still  
something else.

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

On 2/14/07, Nic James Ferrier <nferrier@...> wrote:
>
> I think one could easily produce a series of qualitative tests for
> HTTP based web services to establish their RESTfull goodness.
>
> One would have to come up with a list of attributes of RESTfull
> systems:
>
> - what's the content types?
> - does it support HEAD properly?
> - what happens when you do methods that aren't supported? etc...
>
> and then apply weights to each of them.
>
> Then write a client to test a webapp for each of the attributes (we
> might call them constraints /8-) and then produce a report.
>
> Anyone interested in doing this with me?

I am certainly interested in collaboration - both with other people's
efforts and bringing the knowledge of others into my own efforts.

Alan Dean
http://thoughtpad.net/who/alan-dean/news

Stefan Tilkov wrote:
> On Feb 14, 2007, at 7:29 PM, Bill de hOra wrote:
>> J�r�me Louvel wrote:
>> >
>> >
>> > Hi Bill,
>> >
>> > You can apply for an Expert Group Nomination at:
>> > http://www.jcp.org/en/jsr/egnom?id=311
>> > <http://www.jcp.org/en/jsr/egnom?id=311>
>>
>> Thanks J�r�me. I've just submitted a nomination request.
>>
>> cheers
>> Bill
>>
>>
>
> I just did the same.
>
> Stefan
> -- 
> Stefan Tilkov, http://www.innoq.com/blog/st/
>
>
As did I.

Pete

Paul Downey wrote:
> 
> 
> 
> On 14 Feb 2007, at 15:56, Elliotte Harold wrote:
>  > Do we really want to trust these folks to define the official Java
>  > spec
>  > for REST? Please read the JSR, and send comments to jsr-311-
>  > comments@... <mailto:comments%40jcp.org>
> You know, I think I trust Marc et all to come up with
> something worthwhile and put it in the hands of a
> lot of developers.
> 
> What worries me most about REST is that it isn't testable.

But it is explicit. It's difficult to say that about SOA. Then again is 
this really a useful way to speak - I could say "what worries me about 
design patterns is that they aren't testable" - but what would that mean?

cheers
Bill

Nic James Ferrier wrote:

> Roy has complained before about the term being hijacked. 

That's either going to happen or we become the smug Lisp weenies of 
distributed systems. The question is are the REST community (us) and 
software designers who are prepared to work under the REST style "ready 
for success"? I'd say no.

if you look at what Fowler has said about OO, that lots of strange 
things were done in its name, I think will happen around REST. It's part 
of being adopted. Then again, if it came down to it, good luck 
persuading anyone you know more about OO than him.


> it is slightly dangerous to talk about RESTfull toolkits and REST
> support. I am quite happy for people to say "this one thing is more
> RESTfull than this other thing". As long as it is of course.

"Where are the REST toolkits" is one of my favorite quotes of the last 
few years, partially because it's so right and so wrong. Perhaps it is 
the wrong way to think about things, but you could *never* persuade me 
that there is adequate technical support for building in the REST style 
today. Most frameworks are RPC/Gateway driven which results in bad hard 
to maintain web software - you develop in the REST style on most popular 
frameworks and you'll ship late. That's without even getting into arcana 
like rolling your own etags and figuring out where to leave them.

cheers
Bill

Bill de hOra <bill@...> writes:

> That's either going to happen or we become the smug Lisp weenies of 
> distributed systems. The question is are the REST community (us) and 
> software designers who are prepared to work under the REST style "ready 
> for success"? I'd say no.

Hey. I'm a smug lisp weenie.


> "Where are the REST toolkits" is one of my favorite quotes of the last 
> few years, partially because it's so right and so wrong. Perhaps it is 
> the wrong way to think about things, but you could *never* persuade me 
> that there is adequate technical support for building in the REST style 
> today. Most frameworks are RPC/Gateway driven which results in bad hard 
> to maintain web software - you develop in the REST style on most popular 
> frameworks and you'll ship late. That's without even getting into arcana 
> like rolling your own etags and figuring out where to leave them.

Certainly there are better HTTP toolkits that need to be written.

I was doing some openid hacking the other day with python's urllib2 -
supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
my fingers in a door. It was a deeply unpleasant experience.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Marc, I already explained to Rajiv last November that I would not
allow Sun to go forward with the REST name in the API.  It doesn't
make any sense to name one API as the RESTful API for Java, and I
simply cannot allow Sun to claim ownership of the name (which is
what the JSR process does by design).  Change the API name to
something neutral, like JAX-RS.

....Roy

On 15 Feb 2007, at 00:08, Bill de hOra wrote:
> > What worries me most about REST is that it isn't testable.
>
> But it is explicit. It's difficult to say that about SOA.

yeah, I'm not speaking in favour of SOA, just that REST
could be a little more concrete. OK not REST, but I'd
like some more concrete to point at and advise people
to emulate.


> Then again is this really a useful way to speak - I could
> say "what worries me about
> design patterns is that they aren't testable"
> - but what would that mean?


That's fair comment, but if you use a framework (Hmm. is it a
framework, dunno) such as JSR 311, then chances
are you're going to expose your service RESTfully, and
that can only be goodness.

--
http://blog.whatfettle.com

Nic James Ferrier wrote:

> I was doing some openid hacking the other day with python's urllib2 -
> supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
> my fingers in a door. It was a deeply unpleasant experience.

Try this one:

  http://bitworking.org/projects/httplib2/

cheers
Bill

Bill de hOra <bill@...> writes:

> Nic James Ferrier wrote:
>
>> I was doing some openid hacking the other day with python's urllib2 -
>> supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
>> my fingers in a door. It was a deeply unpleasant experience.
>
> Try this one:
>
>   http://bitworking.org/projects/httplib2/

Yeah... it's nice. But the fact that there are good frameworks out
there wasn't my point.

urllib2 comes with python, a language that supposedly gets the
web. And urllib2 really sucks.

Similarly, let's hear it for HttpURLConnection. Java, that famous
Internet language, has a really bad http client library.

And these are just the clients.


Really, when I want to do something client side I tend to use curl.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Feb 14, 2007, at 6:36 PM, Roy T. Fielding wrote:

> Marc, I already explained to Rajiv last November that I would not
> allow Sun to go forward with the REST name in the API.  It doesn't
> make any sense to name one API as the RESTful API for Java, and I
> simply cannot allow Sun to claim ownership of the name (which is
> what the JSR process does by design).  Change the API name to
> something neutral, like JAX-RS.
>
Roy,

I think we may have gotten our wires crossed somewhere, when you  
discussed this with Rajiv last November you certainly didn't rule out  
any name with REST in it, e.g. here is a quote from an email you sent  
on Nov 30th in response to an email from Rajiv exploring names that  
would be OK with you.

>> Java API for XML programming in the REST Style - JAX-RS.
>>
>
> Sure, that's a fine name, especially if you intend it to be limited
> to XML messages.

The name we adopted is "Java API for RESTful Web Services" since the  
API won't be XML specific. This isn't very different from the name  
you approved of earlier.

Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.

On 2/14/07, Paul Downey <paul.downey@...> wrote:
> What worries me most about REST is that it isn't testable.

Eeek!  REST is most definitely testable.  See sec 5 of Roy's
dissertation for the tests (constraints).

I agree that calling a Java API "RESTful" is a misnomer though.  If it
was described as "supporting RESTful application development", that
would be better.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On 2/14/07, Nic James Ferrier <nferrier@...> wrote:
>  I was doing some openid hacking the other day with python's urllib2 -
>  supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
>  my fingers in a door. It was a deeply unpleasant experience.

In a shameless bit of self-promotion, you should
really be using httplib2:

   http://bitworking.org/projects/httplib2/

   -joe

-- 
Joe Gregorio        http://bitworking.org

On 2/14/07, Jerome Louvel <contact@...> wrote:
>
>  Let's not waste this opportunity to properly standardize REST on Java.

Does the Expert Group include anyone who has written such an API
already? For example, Jetty has had something similar for years.

Also, you are standardizing a server-side HTTP API, not REST. From
what I have seen so far, it looks like something I would use, but
please rename it.

-- 

Robert Sayre
<http://blog.mozilla.com/rob-sayre/>
"I would have written a shorter letter, but I did not have the time."

On 2/14/07, Elliotte Harold <elharo@...> wrote:
>  This is like asking Karl Rove and Dick Cheney to write the Democratic
>  Party platform.

Ouch. That's unnecessarily sharp. I've worked with Marc on
the URI Template spec and he's smart, easy to work with, and in
no way deserves this kind of personal attack.

>  I hope we can derail this completely, but we probably can't. If not, are
>  there any JSR members here who might join the working group and bring
>  some sanity and actual REST experience to the development of the
>  eventual specification? If we can't stop it, maybe we can at least limit
>  the damage.

I *do* have my concerns about the process and the end results of
a JSR with the term REST attached to it, only because
I can imagine a near future where the "definition" of REST to the
average Java programmer is anything you can build with a JSR 311 library,
and the converse, that anything you can't build with a JSR 311 library
is not RESTful.

   -joe

-- 
Joe Gregorio        http://bitworking.org

Nic James Ferrier wrote:
> urllib2 comes with python, a language that supposedly
> gets the web. And urllib2 really sucks.

What's wrong with it? (he asks after just making the decision to focus the
vast majority of his next language learning time on python...)

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

On 14.02.2007, at 19:32, Stefan Tilkov wrote:

> I've exchanged emails with Marc Hadley, collected some reactions  
> and published a news item here:
>
> http://www.infoq.com/news/2007/02/jsr-311-java-rest-api

Stefan,

good overview, thanks. Also gives me some hope :-)

I think the JSR provides a good opportunity to discuss REST  
principles in a practical/implementation context. I expect to see a  
lot of "Naa...you cannot do that because..." kinds of discussions  
with associated AHA-Moments - well, if the group accepts my application.

Jan



>
> Stefan
> --
> Stefan Tilkov, http://www.innoq.com/blog/st/
>
>

"Mike Schinkel" <mikeschinkel@...> writes:

> Nic James Ferrier wrote:
>> urllib2 comes with python, a language that supposedly
>> gets the web. And urllib2 really sucks.
>
> What's wrong with it? 

It's very complex and not as configurable as it should be.

I have been doing something interesting with SSL lately and was using
Python. Python's default socket implementation is broken for client
certificates (it assumes some mad defaults). Consequently urllib2 is
broken as well.

And here is what I had to do to get a working urllib2:

  # HTTPS client based on OpenSSL
  import urllib2
  import httplib
  import socket
  import OpenSSL
  import traceback


  class MyFakeSocket(httplib.FakeSocket):
      def send(self, *args):
          return self._ssl.send(*args)

      def sendall(self, *args):
          return self._ssl.sendall(*args)

      def recv(self, *args):
          return self._ssl.recv(*args)

  class MyHTTPSConnection(httplib.HTTPConnection):
      "This class allows communication via SSL."

      default_port = httplib.HTTPS_PORT

      def __init__(self, host, port=None):
          httplib.HTTPConnection.__init__(self, host, port)

      def connect(self):
          "Connect to a host on a given (SSL) port."
          sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
          sock.connect((self.host, self.port))
          ctx = OpenSSL.SSL.Context(OpenSSL.SSL.SSLv3_METHOD)
          ssl = OpenSSL.SSL.Connection(ctx, sock)
          ssl.connect_ex((self.host, self.port))
          self.sock = MyFakeSocket(sock, ssl)


  class MyHTTPSHandler(urllib2.HTTPSHandler):
      def https_open(self, req):
          return self.do_open(MyHTTPSConnection, req)


  def init():
      try:
          https_handler = MyHTTPSHandler()
          od = urllib2.build_opener(https_handler)
          urllib2.install_opener(od)
      except Exception, e:
          traceback.print_tb(sys.exc_info()[2])
          print str(e)


Unfortunately, in order to find out how to do that I had to read
through the code. I'll blog this somewhere soon so that the python
universe is improved a little bit but I think I'd advise using the
kitkeeper library if you're doing any http hacking.


> (he asks after just making the decision to focus the
> vast majority of his next language learning time on python...)

I'd applaud that. Python has some really nice points (and some really
bad points: like no declaration of variables). But it's HTTP client
really sucks.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Joe Gregorio wrote:
> On 2/14/07, Nic James Ferrier <nferrier@...> wrote:
>>  I was doing some openid hacking the other day with python's urllib2 -
>>  supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
>>  my fingers in a door. It was a deeply unpleasant experience.
> 
> In a shameless bit of self-promotion, you should
> really be using httplib2:
> 
>   http://bitworking.org/projects/httplib2/

Any chance of getting httplib2 into the standard library Joe?

cheers
Bill

There's an assumption so far in this thread that the 311 proposal is 
purely a server side technology. However, I can find nothing in the JSR 
to explicitly indicate this or contradict it. (The sheer vagueness of 
the proposal is a major problem, and a big reason why this should be 
done as an open source project *outside* the JCP first, before 
standardization. If that were the case I'd have many fewer concerns with 
it.)

However reading between the lines I see some evidence that this plays 
both sides of the fence. I think there's an assumption that tools will 
be used on the one side to consume what the server side produces. For 
instance they might share a WADL file. If so, this would weaken or break 
the client independence of HTTP. We'd be back in WS-Hell where 
theoretically independent services can only be consumed by clients 
written with the same framework.

One of two things needs to happen here:

1. The JSR is rewritten to make it clear that this is purely a 
server-side proposal and that no client side technology will be specced.

2. If the goal is to develop both client and server APIs, then this 
needs to be split into two independent JSRs, with separate spec leads 
and expert groups. Furthermore there should be a wall between the two 
efforts. They must not act as if they know what the other is doing. The 
client group should design for nothing but a generic HTTP server, and 
the server group should design for nothing  more than a generic HTTP 
client. Neither may depend on any functionality of the other. For 
example, a server side Representation class should not share code or 
interface with a client Representation class.  Doing that risks 
introducing unintended dependencies and tightly couple 311 clients to 
311 servers.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

[ Attachment content not displayed ]

Hi All,


Guess this is the right forum to post this question.

I am supposed to make a shopping cart solution. Though I have options
like osCommerece and ZenCart I would like to go for something which
has exposed itself as web service ( preferably RESTful, why not ? :)
). That will help me develop my client ( Ajax based with jQuery or
some other JavaScript framework ) without old,
throw-all-content-to-user shopping cart pages. I tried to search on
net but in vain. Infact have tried to search module for osCommerce (
anything for that matter ) which gives me   all basic e-commerce
feature as web service, but couldn't find one. 

Have anybody come across piece of software which can help me ? 


Thanks in advance,

Samyak

Hi Elliotte,

In my mind this JSR is only aimed at server-side applications.
However, if you take the Restlet API, it is both a server-side and
client-side API and we see this as a strong advantage compared
existing solutions requiring you to learn two different APIs (Servlet
API + HttpURLConnection for example). 

If you take the case of a reverse proxy, our Representation class can
be retrieved by a client HTTP connector from a remote origin server
and then directly forwarded to the original client via the server HTTP
connector.

Could you explain what is wrong in ensuring consistency (where it
makes senses) between both sides? IMO, more an more Web applications
can't be strictly categorized as client-side or server-side (ex:
mash-ups) so this wall that you want to raise seems unnecessary.

Regards,
Jerome

Jérôme Louvel wrote:

> Could you explain what is wrong in ensuring consistency (where it
> makes senses) between both sides? IMO, more an more Web applications
> can't be strictly categorized as client-side or server-side (ex:
> mash-ups) so this wall that you want to raise seems unnecessary.

One goal of both WS-* and REST is that clients written in a multitude of 
languages on a multitude of platforms will be able to talk to each other 
interoperably. The server does not care what language the client is 
written in and vice versa. At least that's the theory.

In practice WS-* doesn't actually interoperate all that well. .NET 
servers work with .NET clients and Java servers work with Java clients 
(if they use the same basic framework) but just try getting .NET servers 
to talk to Java clients or vice versa. You can do it, but it takes lots 
of debugging and detailed knowledge of which pieces of which specs are 
and are not reliable between platforms. Consequently most intranet 
services are platform-locked and most Internet services aren't used all 
that much.

Even when interoperability is the goal, lots of little assumptions tend 
to get baked into the libraries that prevent other libraries from 
communicating. Sharing classes between the client and server is a real 
code smell.

Consider a Representation class, for example. The server sends a 
representation and the client receives it, so it should be appropriate 
for them to use the same class to model it, right? Actually no. The 
client and server have different views of this object. For instance the 
server is probably going to want some sort of pointer back to the actual 
resource from which the representation is derived while the client 
should not see any such pointer. Furthermore, the client needs a way to 
get a byte array or InputStream for the message body in the 
Representation. The server needs a way to set the byte array or get an 
OutputStream for the message body. If you try to get away with one 
Representation class, then each side will have methods it doesn't need.

The only way to get the ideal client API is to design just a client API. 
The only way to get the best serve side API is to design just a server 
side API. If REST is done right, then we shouldn't need to coordinate 
the two design efforts. The interfaces between the two should be limited 
to HTTP.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Elliotte,

Interoperability between clients and servers at the wire level is
different from consistency between client-side and server-side API
design, especially when several implementations of the same API are
expected. In our case (RESTful Web services API), the common
denominator should be all of HTTP 1.1 and just HTTP 1.1.

I don't think it would be wise to include any kind of object
serialization to/from XML in such API if that is your concern. We
don't want to fall into WS-* interop issues as you correctly point.

> Consider a Representation class, for example. The server sends a 
> representation and the client receives it, so it should be appropriate 
> for them to use the same class to model it, right? Actually no. The 
> client and server have different views of this object. For instance the 
> server is probably going to want some sort of pointer back to the
actual 
> resource from which the representation is derived while the client 
> should not see any such pointer. 

Talking about the Restlet's Representation class, it doesn't contain
any reference to the parent Resource, so that is not an issue for us.
We never had an user complaining about this design choice. 

> Furthermore, the client needs a way to get a byte array or
InputStream for the message body in the Representation. The server
needs a way to set the byte array or get an 
> OutputStream for the message body. If you try to get away with one 
> Representation class, then each side will have methods it doesn't need.

In our case, we designed the Representation class like a Content (or
like an HTTP entity if you prefer) that can be either written to an
OutputStream (or to an NIO WritableByteChannel) or read by getting an
InputStream (or an NIO ReadableByteChannel). We have several abstract
implementations that can let you automatically convert from one IO
mode to another. Have a look at this hierarchy diagram:
http://www.restlet.org/tutorial#conclusion

Check also the Javadocs of the org.restlet.resource package:
http://www.restlet.org/docs/api/org/restlet/resource/package-summary.html

Best regards,
Jerome

On 2/15/07, Elliotte Harold <elharo@...> wrote:
> The only way to get the ideal client API is to design just a client API.
> The only way to get the best serve side API is to design just a server
> side API. If REST is done right, then we shouldn't need to coordinate
> the two design efforts. The interfaces between the two should be limited
> to HTTP.

I agree.  Moreover, I also think you generally have different design
goals with client and server APIs.  For example performance is
normally a lot more important for servers than clients.  Also, a
simple API might be more desirable on the client than on the server
(again, because of performance).  For these reasons it will likely do
more harm than good to try to use server abstractions in a client API
or vice-versa.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Hi Steve,

You raise some interesting points, detailed discussion of which  
really belong in the expert group once it is formed. For now I'll  
take a shot at some of the higher level questions, answers  
interspersed below.

On Feb 15, 2007, at 6:10 AM, Steve Loughran wrote:
>
> o Why not just have an interface with the well known verbs on? I know
> Java5 makes annotations possible, but it is not clear they are always
> appropriate. Maybe with WS-*, where your endpoints want to marshall
> arbitrary java graphs across a broad set of verbs, but with HTTP you
> have the fairly constrained verb set of Http+DAV,
>
IMO, an interface locks down the method signatures too tightly. Look  
at the example on my blog where I show a URI parameter being injected  
as a method parameter, you can do same kind of thing with query  
parameters, matrix parameters or even HTTP headers but to do that you  
need to leave the method signatures flexible.

> o It should be the option of the of previous elements in the directory
> path to dynamically determine which resource classes should receive
> the next part of the path. That is, not merely a simple regexp mapping
> of url->resource, but something that multiple components can
> dynamically resolve.
>
> o Is this intended to be an adjunct to Java EE, something to export
> session beans over HTTP, or something svelte that runs atop something
> minimal like jetty?
>
Its intended to run atop a variety of HTTP servers, I'd like to see  
Jetty supported. We have some ideas for a container SPI that should  
allow an impl to be hosted on top of any container that can make the  
request information available and write a response.

> o Is this going to be the place where the servlet API gets looked at,
> for the first time in a decade? I recall discussing with the Java EE
> spec leads the absence of any annotations to make writing servlets as
> easy as it is to do stateful Java EE session beans; for some reason
> you dont need to edit any XML files to create a WS epr bound to a
> session bean, yet to write your own servlet you need to code web.xml
> files or play with XDoclet.
>
This isn't intended to replace Servlet, deployment within a servlet  
container is one of the options called out explicitly in the JSR.

> o Is JAX-RS going to focus on O/X mapping as the best way to work with
> XML, with JAXB 2.0 as the mapping system?
>
No, though it should be easy to plug in JAXB if you want to use it.  
We have some ideas for a representation SPI that should allow you to  
plug in support for a variety of serialization/deserialization  
technologies.

> o Is the server-side metaphor still going to be something with the
> flavour of RPC? OR something that makes effective use of the NIO and
> concurrency libraries
>
The server side metaphor should be that of a uniform interface. Sync  
vs async is a very good question and one I think the expert group  
needs to spend some cycles on.

> o What's the fault model going to be? What happens if a method throws
> an exception?
>
It gets converted into an appropriate HTTP status code.

> o What public repository is the TCK test suite going to be hosted in
> (apache, java.net, google, sourceforge?), and will you be using JUnit
> or TestNG with HttpUnit/XmlUnit?
>
All TBD.

> I am seriously debating joining this group, perhaps even as an
> representative of an organisation. However I am concerned not just
> about the basic architecture, but about the test process.
>
> I am currently finalising the interop result documents for an
> OASIS-based standard, one built on the house of cards that is WS-*,
> and have come to some strong opinions about how test-driven standards
> can be, in contrast to things like WS-A where testability was clearly
> an afterthought (see attached document). While I celebrate the fact
> that the JCP, unlike the W3C or OASIS, has a test-centric process, I
> have seen how hard it is for OSS projects to even get access to the
> TCK to products such as JAX-WS, creating a barrier to testing and
> redistribution. A public TCK that could be checked out a build under
> Gump would let downstream implementations also build and test nightly,
> and it would let the implementors add more test cases to the TCK as
> they encountered problems or ambiguity.
>
> Returning to the architecture. Anything that tries to bring the same
> ease of use of building WS-* to the REST world has missed something
> obvious. While JAX-WS may make it easy to export a java method to the
> rest of the world, it does nothing to ensure the world can talk to it.
> If there are things from the Java world we ought to borrow, it could
> be
>
> -the option of generating structured faults, be they SOAPFaults or
> XHTML with machine parseable content. Not using the "transparent"
> marshalling of JAX-WS, but something more like I describe in my M32
> paper; having an interface that faults can implement if they want to
> generate their own XML/XHTML
>
Sounds like a nice idea. I wouldn't tie it XML though, an endpoint  
might want to support other formats like JSON too.

> -a handler chain for incoming content instead of relying on what is
> built in to the system. There is already much of this built in to
> Apache Tomcat, of course.
>
I have mixed feelings about handler chains, as you note that sort of  
functionality is already built into a variety of containers.

> -a programmatic way to configure things. Right now the normal servlet
> API is purely declarative, except for system-specific APIs. I need the
> right to add an remove resource mappings dynamically.
>
Also an interesting idea.

Regards,
Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.

Paul Downey wrote:
> On 15 Feb 2007, at 00:08, Bill de hOra wrote:
>>> What worries me most about REST is that it isn't testable.
>> But it is explicit. It's difficult to say that about SOA.
> 
> yeah, I'm not speaking in favour of SOA, just that REST
> could be a little more concrete. OK not REST, but I'd
> like some more concrete to point at and advise people
> to emulate.

Build a RESTful standard. Build tests for it. You've now got testable 
REST and the rest of us can choose to use it or not.

>> Then again is this really a useful way to speak - I could
>> say "what worries me about
>> design patterns is that they aren't testable"
>> - but what would that mean?
> 
> 
> That's fair comment, but if you use a framework (Hmm. is it a
> framework, dunno) such as JSR 311, then chances
> are you're going to expose your service RESTfully, and
> that can only be goodness.

Depends on how much freedom it gives you. You could say we've a (fairly) 
RESTful (and testable) framework in RFC 2616 and the various tools that 
use it (browsers, servers, server-side scripting languages, XMLHTTP, et 
al). You could argue that these give you too much freedom and hence its 
possible to not behave RESTfully with them (though experience shows that 
those with the least freedom tend to actually force you to be unRESTful 
rather than to be RESTful).

Personally I don't give a damn about testability of REST. I am a big fan 
of REST (evangelical even) but I will personally break every single 
principle of REST to get a job done. The reason I generally don't is 
that those principles give me real benefits. *THAT* is testable.

Don't test REST, test its results.

Hi Mark,

> I agree.  Moreover, I also think you generally have different design
> goals with client and server APIs.  For example performance is
> normally a lot more important for servers than clients.  Also, a
> simple API might be more desirable on the client than on the server
> (again, because of performance).  For these reasons it will likely do
> more harm than good to try to use server abstractions in a client API
> or vice-versa.

I understand your point of view, but we also have to take into account
applications that need high performance for clients too.
Implementating transparent RESTful proxies for non-RESTful
applications is a common use case where you need excellent
performance, multi-threading on both sides of your application. 

FYI, we provide two client HTTP connectors (pluggable and using the
same API), one based on JDK's HttpURLConnection and another based on
Apache HTTP Client library. 

Also, in our case, you can directly set the client's output
representation reference as the server's output representation,
without reading/buffering anything. An optimized implementation of the
Restlet API could even directly move bytes from client socket to
server socket without consuming JVM memory thanks to Java's NIO.

Anyway, we didn't find the sharing of common classes between the
server-side and the client-side of the API to be an issue, it's even
the opposite. For this design, we leveraged the notion of REST uniform
interface (see our org.restlet.Uniform class) and the generic HTTP
message aspects (entity headers common to both HTTP requests and
responses). Just think about representations metadata (ETag, media
type, encoding, etc.), their are strictly the same.

Even the HTTP specification doesn't provide two separate definitions
for requests and responses depending on whether you see the
communication from the client end or from the server end of the
connection, so why redefine them twice at the API level? 

Best regards,
Jerome

Jérôme Louvel wrote:
> Elliotte,
> 
> Interoperability between clients and servers at the wire level is
> different from consistency between client-side and server-side API
> design, especially when several implementations of the same API are
> expected. In our case (RESTful Web services API), the common
> denominator should be all of HTTP 1.1 and just HTTP 1.1.

Multiple implementations of the same API is rarely necessary and has 
resulted in overly complex designs throughout the Java class library. 
The big smell is use of the abstract factory design pattern. That's a 
sure sign of architecture astronautics and a confusing, hard-to-use, 
hard-to-deploy API.

If multiple implementation are necessary, they should operate by 
replacing the JAR file with their own classes, not by using abstract 
factories to choose from among different classes at runtime. Abstract 
factories are only appropriate when the *same executing program* needs 
simultaneous access to more than one implementation. This rare and not 
the case here.

Of course, adopting this principle would mean that the resulting work 
could not be bundled into the JDK. This would be a good thing. The JDK 
is already too big, and most people don't need this. This project makes 
a lot more sense a non-standard, open source development that can stand 
or fall on its own strengths and weaknesses, rather than one that is 
propped up by being bundled with the JDK.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 2/15/07, Bill de hOra <bill@...> wrote:
>  Any chance of getting httplib2 into the standard library Joe?

That's always been a stated goal of the project, though I need
to submit all the right forms and put a little more polish on
the library before I actively start lobbying for that.

  -joe

-- 
Joe Gregorio        http://bitworking.org

On 2/15/07, J�r�me Louvel <contact@...> wrote:
> Hi Mark,
>
> > I agree.  Moreover, I also think you generally have different design
> > goals with client and server APIs.  For example performance is
> > normally a lot more important for servers than clients.  Also, a
> > simple API might be more desirable on the client than on the server
> > (again, because of performance).  For these reasons it will likely do
> > more harm than good to try to use server abstractions in a client API
> > or vice-versa.
>
> I understand your point of view, but we also have to take into account
> applications that need high performance for clients too.

Then they can use an

> Implementating transparent RESTful proxies for non-RESTful
> applications is a common use case where you need excellent
> performance, multi-threading on both sides of your application.
>
> FYI, we provide two client HTTP connectors (pluggable and using the
> same API), one based on JDK's HttpURLConnection and another based on
> Apache HTTP Client library.
>
> Also, in our case, you can directly set the client's output
> representation reference as the server's output representation,
> without reading/buffering anything. An optimized implementation of the
> Restlet API could even directly move bytes from client socket to
> server socket without consuming JVM memory thanks to Java's NIO.
>
> Anyway, we didn't find the sharing of common classes between the
> server-side and the client-side of the API to be an issue, it's even
> the opposite. For this design, we leveraged the notion of REST uniform
> interface (see our org.restlet.Uniform class) and the generic HTTP
> message aspects (entity headers common to both HTTP requests and
> responses). Just think about representations metadata (ETag, media
> type, encoding, etc.), their are strictly the same.
>
> Even the HTTP specification doesn't provide two separate definitions
> for requests and responses depending on whether you see the
> communication from the client end or from the server end of the
> connection, so why redefine them twice at the API level?

Seriously?  I already gave an example of why they might need to be
different; because the requirements and/or design goals may be
different.

That's not saying there won't be any shared API - I expect you could
share a bunch of "util" classes.  But I don't think it should be a
goal to be able to share important chunks of the API between client
and server.  If that happens because the goals are similar enough,
great, but it shouldn't itself be an objective IMO.

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Jérôme Louvel wrote:

> In our case, we designed the Representation class like a Content (or
> like an HTTP entity if you prefer) that can be either written to an
> OutputStream (or to an NIO WritableByteChannel) or read by getting an
> InputStream (or an NIO ReadableByteChannel).

I haven't had as much time to spend getting familiar with RESTlet as I 
would like, but that's partially a function of its complexity, and 
that's partially a function of it working on both the client and the 
server. Programs that act as both HTTP clients and servers are rare. 
Usually I'm either writing a client or a server, not both.

If RESTlet were a pure server API, it would be simpler and I could learn 
it and work with it faster. Ditto if it were a pure client API. I'm 
unlikely to want both at the same time in the same program but because 
you've tried to cover both use cases in the same product , it's become 
quite a bit larger than it needs to be. The learning curve is not 
linear. Complexity grows faster than the API footprint.

Now are there times when I want both? Yes, as you point out; but it 
would be easier if I could learn them separately and treat them as 
separate pieces. Or if I could easily use one but not the other. For 
instance, I might want to use RESTlet for the server side but Apache 
HTTPClient for the client.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Marc Hadley wrote:
> Hi Steve,
> 
> You raise some interesting points, detailed discussion of which really 
> belong in the expert group once it is formed. 

We're still waiting to hear if everyone is welcome in the expert group 
forum or if it will be a closed discussion. I hope it's the former, but 
if it's the latter, I expect people will continue kibitzing here.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

On 2/15/07, Mark Baker <distobj@...> wrote:
> On 2/15/07, J�r�me Louvel <contact@...> wrote:
> > Hi Mark,
> >
> > > I agree.  Moreover, I also think you generally have different design
> > > goals with client and server APIs.  For example performance is
> > > normally a lot more important for servers than clients.  Also, a
> > > simple API might be more desirable on the client than on the server
> > > (again, because of performance).  For these reasons it will likely do
> > > more harm than good to try to use server abstractions in a client API
> > > or vice-versa.
> >
> > I understand your point of view, but we also have to take into account
> > applications that need high performance for clients too.
>
> Then they can use an

Oops.  Meant to say "They can use a high performance client API then".

Mark.
-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

Elliotte Harold wrote:
> Programs that act as both HTTP clients and servers are rare. 
> Usually I'm either writing a client or a server, not both.

I'm very often writing programs that handle both sides of that equation 
at the same time. Usually my concerns about the app as a client and as a 
server are very different, so even then I'm not seeing a lot of value in 
there being all that much shared between the two.

Marc Hadley wrote:

>> -a programmatic way to configure things. Right now the normal servlet
>> API is purely declarative, except for system-specific APIs. I need the
>> right to add an remove resource mappings dynamically.


I would suggest that a critical use case is being able to manage this 
from a web-based interface; e.g. like WordPress is configured.  That may 
not be part of the core or the RI, but it should be possible to design a 
  web-based management system for a be site on top of this so that it is 
possible to map file systems and restlets (or whatever) to URL 
structures without having to drop down to code or config files.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Jérôme Louvel wrote:

> Even the HTTP specification doesn't provide two separate definitions
> for requests and responses depending on whether you see the
> communication from the client end or from the server end of the
> connection, so why redefine them twice at the API level? 

The spec defines what it is. The API defines what you can do with it. 
The different ends of the connection want to do different things with 
the medium of transfer and consequently view it in different ways.

This is hardly unique to HTTP or software by the way. For instance, 
McDonald's sees a hamburger very differently than I as a customer do. 
For them it is an inventory item. For me it is lunch. Their operations 
on the hamburger include reordering and cooking. Mine include eating.


-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Jérôme Louvel wrote:

> I understand your point of view, but we also have to take into account
> applications that need high performance for clients too.
> Implementating transparent RESTful proxies for non-RESTful
> applications is a common use case where you need excellent
> performance, multi-threading on both sides of your application. 
> 

There is not one API or library to rule them all, nor should their be, 
though standardization often attempts to create such a beast. Different 
use cases require different libraries and APIs, even when they're doing 
roughly the same thing, just at different scales.

The JDK needs a solid client side HTTP API, one that's better than 
java.net.URL. This library should be optimized and designed for simple 
use cases, and be adequate up to about the use a web browser or Atom 
client would put it to.

If you're building a network proxy server or a multimillion feed 
aggregator such as Bloglines, you need a different HTTP library to suit 
your needs. I do not think this use case is common enough to justify 
bundling such a thing with the JDK. Nor do I think we should try to make 
one library serve both ends of the spectrum.

I suspect server side libraries should be limited to JEE and kept out of 
JSE in general. Not everything needs to be bundled with the JDK in order 
to be useful.

-- 
Elliotte Rusty Harold  elharo@...
Java I/O 2nd Edition Just Published!
http://www.cafeaulait.org/books/javaio2/
http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/

Elliotte,

> I haven't had as much time to spend getting familiar with RESTlet as
> I would like, but that's partially a function of its complexity, and 
> that's partially a function of it working on both the client and the 
> server. 

In just two lines you can output the content of a Web page to the
console. I don't think it is that complex compared to other APIs I've
seen: 

   Client client = new Client(Protocol.HTTP);
   client.get("http://www.restlet.org").getEntity().write(System.out);

Here is the simplest Restlet server you can build, no XML config
needed, no annotation, no container required, just a couple of JARs in
your classpath:

        Restlet restlet = new Restlet() {
            public void handle(Request request, Response response) {
                response.setEntity("Hello World!", MediaType.TEXT_PLAIN);
            }
        };

        // Create the HTTP server and listen on port 8182
        new Server(Protocol.HTTP, 8182, restlet).start();

Of course, we support more complex cases like routing based on URI
templates, virtual hosting, transparent content negotiation.

> Programs that act as both HTTP clients and servers are rare. 
> Usually I'm either writing a client or a server, not both.

I have seen other usages but that is not the most important point.
Just the fact that you can reuse your knowledge of the API when
writing a pure client then later a pure server seems useful no?

[...]

> Now are there times when I want both? Yes, as you point out; but it 
> would be easier if I could learn them separately and treat them as 
> separate pieces. Or if I could easily use one but not the other. For 
> instance, I might want to use RESTlet for the server side but Apache 
> HTTPClient for the client.

Nothing prevents you from doing that if you feel like it. The Restlet
framework never forces you to use the more complex artifacts if you
don't need them. But it seems nice to know they are here when needed.

Best regards,
Jerome

PS: The exact spelling is "Restlet" instead of "RESTlet" :-)

On Thu, Feb 15, 2007 at 12:03:12AM +0000, Bill de hOra wrote:
> Nic James Ferrier wrote:
> 
> > I was doing some openid hacking the other day with python's urllib2 -
> > supposedly quite a modern HTTP tool. Frankly I'd rather have slammed
> > my fingers in a door. It was a deeply unpleasant experience.
> 
> Try this one:
> 
>   http://bitworking.org/projects/httplib2/

Does httplib2 provide a way to set timeouts? I didn't see that in the
docs.

<rant>
That's been my biggest complaint with python's standard network client
libraries.  Everything is in blocking mode with no timeout.  And the
higher-level libraries like httplib don't provide any way to change
that, so you're left with socket.setdefaulttimeout() which is (ugh)
global.

If you can get a handle to the underlying socket you can always call
socket.settimeout(), but httplib makes that very inconvenient: you
can't do it using the simple request() method.  So instead you have to
do the whole connect(), putrequest(), putheader(), endheaders(),
send(), getresponse() sequence by hand; and you'd have to look at the
source of httplib.py to find out that the socket is at self.sock after
connect() has been called, so you then call foo.sock.settimeout(t).

Which still doesn't help if the call to sock.connect() hangs, because
HTTPConnection.connect() both creates the socket and then calls
sock.connect(). As the socket module documentation says: "Note that
the connect() operation is subject to the timeout setting, and in
general it is recommended to call settimeout() before calling
connect()."  So you're stuck with needing to call the global
socket.setdefaulttimeout(), or (probably better) write a subclass of
HTTPConnection that isn't so stupid.

The end result is that the easy stuff is useless in the real world,
and the poor beginner has to read and understand the source code of
httplib.py just to write an app that won't hang.

That all adds up to a pretty huge WTF in my opinion.
</rant>

--

Paul Winkler
http://www.slinkp.com

Paul Winkler <pw_lists@...> writes:

<rant>
<edited/>
> That all adds up to a pretty huge WTF in my opinion.
> </rant>

I agree... the opportunity for reuse is very low.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Mark,

> Seriously?  I already gave an example of why they might need to be
> different; because the requirements and/or design goals may be
> different.

Sorry, I missed your example. Could you point it to me?

> That's not saying there won't be any shared API - I expect you could
> share a bunch of "util" classes.  But I don't think it should be a
> goal to be able to share important chunks of the API between client
> and server.  If that happens because the goals are similar enough,
> great, but it shouldn't itself be an objective IMO.

In our case, that was a goal added soon in the design process when we
realized we were duplicating too many artifacts. We even use the
same API to access to the file system (using file:// URIs), to the
classloader resources, to SMTP and JDBC servers. REST talks itself
about proxies to non-HTTP protocols. 
http://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm#sec_5_3_1

Of course, that isn't intended to replace dedicated SMTP, JDBC or File
APIs, but we've found it to be a useful level of abstraction. 

Best regards,
Jerome

At Thu, 15 Feb 2007 11:25:05 -0500,
Elliotte Harold wrote:
> The spec defines what it is. The API defines what you can do with it.
> The different ends of the connection want to do different things with
> the medium of transfer and consequently view it in different ways.

This distinction between client & server APIs has hurt the REST style,
in my opinion.

An example: most *client* APIs don’t deal well with large request
bodies. But they do deal well with large response bodies. With server
APIs it is of course the other way round; and most of them insist on
parsing your POSTed request body as x-www-url-encoded, even when it’s
not.

The REST style seems to encourage, as well, intermediary components:
caches, gateways, etc. A uniform client/server http API makes these
sort of components much easier to write.

I would rather have seen a low-level API to get at the http spec as
it is written, and then a simple API on top to get at the web as it is
lived.

best,
Erik Hetzner

Erik Hetzner wrote:
> An example: most *client* APIs don’t deal well with large request
> bodies. But they do deal well with large response bodies. With server
> APIs it is of course the other way round; and most of them insist on
> parsing your POSTed request body as x-www-url-encoded, even when it’s
> not.

I don't see anything in the concept of either "client API" or "server 
API" that imlies "Please suck at the following depending on whether you 
are a client or a server".

On 2/15/07, Paul Winkler <pw_lists@...> wrote:
>  Does httplib2 provide a way to set timeouts? I didn't see that in the
>  docs.

No, it doesn't, since it relies upon httlib for functionality, which
has all the problems you enumerated. The only way to set timeouts
for httplib2 is to set a global timeout for sockets.

One of things I will eventually have to do is bring all the
functionality of httplib into httplib2 so I can get my hands
on the underlying socket, which is required for setting
timeouts, using select(), building iterators for responses, etc.

   -joe

-- 
Joe Gregorio        http://bitworking.org

Elliotte,

FYI, JAX-WS is part of J2SE6 [1][2][3]

Whether one likes it or not, there is a tiny http server already in
JDK6 named com.sun.net.httpserver.HttpServer [4]. One probable
motivation for that was support for async scenarios in the WS-* specs.

If i were you, i'd ask hard questions on what (if any!) this JSR 311
has to do with support for HTTP Binding in the WSDL 2.0 spec. Which is
the reason you see JAX-WS mentioned in the description of this JSR.

thanks,
dims

[1] http://www.1060.org/blogxter/entry?publicid=FBF8D553DE3C185F93BB36309619225C&token=
[2] http://blogs.cocoondev.org/dims/archives/004717.html
[3] http://www.theserverside.com/news/thread.tss?thread_id=43499
[4] http://www.google.com/search?hl=en&q=com.sun.net.httpserver.HttpServer&btnG=Google+Search



On 2/14/07, Elliotte Harold <elharo@...> wrote:
>
>
>
>
>
>
> It had to happen sooner or later. The big boys are waking up and
>  discovering REST, and naturally they want to protect all us little
>  developers from worrying our pretty little heads about nasty things like
>  HTTP and XML by creating easy-to-use REST frameworks:
>
>  JSR-311 Java API for RESTful Web Services
>  http://jcp.org/en/jsr/detail?id=311
>
>  Remember, these are the same jokers who gave us servlets and the
>  URLConnection class as well as gems like JAX-RPC and JAX-WS. They still
>  seem to believe that these are actually good specs, and they are
>  proposing to tunnel REST services through JAX-WS (Java API for XML Web
>  Services) endpoints.
>
>  They also seem to believe that "building RESTful Web services using the
>  Java Platform is significantly more complex than building SOAP-based
>  services". I don't know that this is false, but  if it's true it's only
>  because Sun's HTTP API were designed by architecture astronauts who
>  didn't actually understand HTTP. This proposal does not seem to be
>  addressing the need for a decent HTTP API on either the client or server
>  side that actually follows RESTful principles instead of fighting
>  against them.
>
>  To give you an idea of the background we're dealing with here, one of
>  the two people who wrote the proposal "represents Sun on the W3C XML
>  Protocol and W3C WS-Addressing working groups where he is co-editor of
>  the SOAP 1.2 and WS-Addressing 1.0 specifications. Marc was
>  co-specification lead for JAX-WS 2.0 (the Java API for Web Services)
>  developed at the JCP and has also served as Sun's technical lead and
>  alternate board member at the Web Services Interoperability Organization
>  (WS-I)."
>
>  The other submitter seems to be a primary instigator of the Fast Infoset
>  effort to hide XML in binary goop.
>
>  This is like asking Karl Rove and Dick Cheney to write the Democratic
>  Party platform.
>
>  Do we really want to trust these folks to define the official Java spec
>  for REST? Please read the JSR, and send comments to jsr-311-comments@...
>
>  I hope we can derail this completely, but we probably can't. If not, are
>  there any JSR members here who might join the working group and bring
>  some sanity and actual REST experience to the development of the
>  eventual specification? If we can't stop it, maybe we can at least limit
>  the damage.
>
>  --
>  Elliotte Rusty Harold  elharo@...
>  Java I/O 2nd Edition Just Published!
>  http://www.cafeaulait.org/books/javaio2/
>  http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/
>                    



-- 
Davanum Srinivas :: http://wso2.org/ :: Oxygen for Web Services Developers

http://www.soafacts.com/

via

http://arcware.net/archive/2007/02/15/SOA-Facts.aspx

At Thu, 15 Feb 2007 19:05:44 +0000,
Jon Hanna <jon@...> wrote:
>
> Erik Hetzner wrote:
> > An example: most *client* APIs don’t deal well with large request
> > bodies. But they do deal well with large response bodies. With server
> > APIs it is of course the other way round; and most of them insist on
> > parsing your POSTed request body as x-www-url-encoded, even when it’s
> > not.
>
> I don't see anything in the concept of either "client API" or "server
> API" that imlies "Please suck at the following depending on whether you
> are a client or a server".

I was a bit unclear. What I’m suggesting is that client & server APIs
have different ways of getting at a message’s body. So server APIs
make it easy to return a large body of data in response to a request,
and client APIs make it easy to process a large body of data returned
as the body of a response, but neither make it easy to deal with a
large body in a request message. Server APIs & implementations make it
easy to get at the parameters of a POSTed x-www-url-encoded body, but
they don’t make it easy to get at a request message body’s bytestream.

Let’s say I’m coding a very simple proxy (if I make an obvious
mistake, let me know here; I’ve never coded a proxy). If I get a POST
request, I want to grab my request headers, figure out where I’m
sending it, make a new request to the upstream server, then pipe the
request body’s stream to an upstream request body’s stream and flush
it. It has been my experience that this activity is complicated by
a lack of uniformity between client & server APIs.

best,
Erik Hetzner

 
On Thursday, February 15, 2007, at 08:31PM, "Alan Dean" <alan.dean@...> wrote:
>http://www.soafacts.com/


REST can kill both, SOA *and* Chuck Norris - in a single nano second.

Jan




>
>via
>
>http://arcware.net/archive/2007/02/15/SOA-Facts.aspx
>
>
>
> 
>Yahoo! Groups Links
>
>
>
>
>

On Thu, Feb 15, 2007 at 02:17:32PM -0500, Joe Gregorio wrote:
> On 2/15/07, Paul Winkler <pw_lists@...> wrote:
> > Does httplib2 provide a way to set timeouts? I didn't see that in the
> > docs.
> 
> No, it doesn't, since it relies upon httlib for functionality, which
> has all the problems you enumerated. The only way to set timeouts
> for httplib2 is to set a global timeout for sockets.

If you're willing to subclass, it's not so bad.
Here's a quick start:


class SlightlyBetterHTTPConnection(httplib.HTTPConnection):
    """HTTPConnection subclass that supports timeouts"""

    def __init__(self, host, port=None, strict=None, timeout=None):
        httplib.HTTPConnection.__init__(self, host, port, strict)
        self.timeout = timeout

    def connect(self):
        """Connect to the host and port specified in __init__."""
        # Mostly verbatim from httplib.py.
        msg = "getaddrinfo returns an empty list"
        for res in socket.getaddrinfo(self.host, self.port, 0,
                                      socket.SOCK_STREAM):
            af, socktype, proto, canonname, sa = res
            try:
                self.sock = socket.socket(af, socktype, proto)
                # Different from httplib: support timeouts.
                if self.timeout is not None:
                    self.sock.settimeout(self.timeout)
                # End of difference from httplib.
                if self.debuglevel > 0:
                    print "connect: (%s, %s)" % (self.host, self.port)
                self.sock.connect(sa)
            except socket.error, msg:
                if self.debuglevel > 0:
                    print 'connect fail:', (self.host, self.port)
                if self.sock:
                    self.sock.close()
                self.sock = None
                continue
            break
        if not self.sock:
            raise socket.error, msg


-- 

Paul Winkler
http://www.slinkp.com

On 2/15/07, Paul Winkler <pw_lists@...> wrote:
>  If you're willing to subclass, it's not so bad.
>  Here's a quick start:

Excellent.

   Thanks,
   -joe

>
>  class SlightlyBetterHTTPConnection(httplib.HTTPConnection):
>      """HTTPConnection subclass that supports timeouts"""
>
>  def __init__(self, host, port=None, strict=None, timeout=None):
>          httplib.HTTPConnection.__init__(self, host, port, strict)
>          self.timeout = timeout
>
>  def connect(self):
>          """Connect to the host and port specified in __init__."""
>          # Mostly verbatim from httplib.py.
>          msg = "getaddrinfo returns an empty list"
>          for res in socket.getaddrinfo(self.host, self.port, 0,
>                                        socket.SOCK_STREAM):
>              af, socktype, proto, canonname, sa = res
>              try:
>                  self.sock = socket.socket(af, socktype, proto)
>                  # Different from httplib: support timeouts.
>                  if self.timeout is not None:
>                      self.sock.settimeout(self.timeout)
>                  # End of difference from httplib.
>                  if self.debuglevel > 0:
>                      print "connect: (%s, %s)" % (self.host, self.port)
>                  self.sock.connect(sa)
>              except socket.error, msg:
>                  if self.debuglevel > 0:
>                      print 'connect fail:', (self.host, self.port)
>                  if self.sock:
>                      self.sock.close()
>                  self.sock = None
>                  continue
>              break
>          if not self.sock:
>              raise socket.error, msg
>
>  --
>
>  Paul Winkler
>  http://www.slinkp.com
>                    



-- 
Joe Gregorio        http://bitworking.org

Hi Alan,

On Feb 15, 2007, at 11:29 AM, Alan Dean wrote:
> http://www.soafacts.com/
Thanks!  That was precious.  My favorite (especially in the context  
of this group :-) is:

> Ancient lore promises the day when a single unifying technology  
> will bring openness and peace to all lands. That technology is not  
> SOA. because SOA killed that technology.

:-)

-- Ernie P.

Elliotte,
 
I've worked with Marc Hadley on WS-Addressing, XML Protocol, URI Templates
and WADL.  While he's done a lot of work on WS-*, he also has done work on
REST/HTTP side of things.  He's very open to learning things so I don't
believe he's trying to "push" a particular agenda.  He's smart, dedicated,
funny, practical, and exactly the right kind of person to work on this.  I
like the fact that the WADL work has Java bindings so it's not just
something abstract or "architecture astronaut"ish as you testily describe
it.   
 
While I agree that improvements can be done on servets, URLConnection, and
JAX-WS, I disagree that this should be derailed in any way.  I plan on
contributing and helping, and I encourage others to do the same.
 
Cheers,
Dave


  _____  

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Elliotte Harold
Sent: Wednesday, February 14, 2007 6:56 AM
To: REST Discuss
Subject: [rest-discuss] Sun proposes to apply Web service standardization
principles to REST



It had to happen sooner or later. The big boys are waking up and 
discovering REST, and naturally they want to protect all us little 
developers from worrying our pretty little heads about nasty things like 
HTTP and XML by creating easy-to-use REST frameworks:

JSR-311 Java API for RESTful Web Services
http://jcp.org/ <http://jcp.org/en/jsr/detail?id=311> en/jsr/detail?id=311

Remember, these are the same jokers who gave us servlets and the 
URLConnection class as well as gems like JAX-RPC and JAX-WS. They still 
seem to believe that these are actually good specs, and they are 
proposing to tunnel REST services through JAX-WS (Java API for XML Web 
Services) endpoints.

They also seem to believe that "building RESTful Web services using the 
Java Platform is significantly more complex than building SOAP-based 
services". I don't know that this is false, but if it's true it's only 
because Sun's HTTP API were designed by architecture astronauts who 
didn't actually understand HTTP. This proposal does not seem to be 
addressing the need for a decent HTTP API on either the client or server 
side that actually follows RESTful principles instead of fighting 
against them.

To give you an idea of the background we're dealing with here, one of 
the two people who wrote the proposal "represents Sun on the W3C XML 
Protocol and W3C WS-Addressing working groups where he is co-editor of 
the SOAP 1.2 and WS-Addressing 1.0 specifications. Marc was 
co-specification lead for JAX-WS 2.0 (the Java API for Web Services) 
developed at the JCP and has also served as Sun's technical lead and 
alternate board member at the Web Services Interoperability Organization 
(WS-I)."

The other submitter seems to be a primary instigator of the Fast Infoset 
effort to hide XML in binary goop.

This is like asking Karl Rove and Dick Cheney to write the Democratic 
Party platform.

Do we really want to trust these folks to define the official Java spec 
for REST? Please read the JSR, and send comments to jsr-311-comments@
<mailto:jsr-311-comments%40jcp.org> jcp.org

I hope we can derail this completely, but we probably can't. If not, are 
there any JSR members here who might join the working group and bring 
some sanity and actual REST experience to the development of the 
eventual specification? If we can't stop it, maybe we can at least limit 
the damage.

-- 
Elliotte Rusty Harold elharo@metalab. <mailto:elharo%40metalab.unc.edu>
unc.edu
Java I/O 2nd Edition Just Published!
http://www.cafeaula <http://www.cafeaulait.org/books/javaio2/>
it.org/books/javaio2/
http://www.amazon.
<http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/>
com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/


 

Jerome,
 
There's a huge difference between a protocol specification such as HTTP and
an API specification for a protocol.  HTTP is the same for both client and
sender because they both see the same things on the wire.  An API could be
dramatically different based upon the needs of clients vs services, and what
kind of infrastructure is available for use.  I'm not saying JSR 311 should
have separate APIs for client/server, just pointing out that there are
scenarios where it is desirable.  
 
Cheers,
Dave
 


  _____  

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of J�r�me Louvel
Sent: Thursday, February 15, 2007 7:48 AM
To: rest-discuss@yahoogroups.com
Subject: [rest-discuss] Re: Another potential problem with the 311 proposal



Hi Mark,

> I agree. Moreover, I also think you generally have different design
> goals with client and server APIs. For example performance is
> normally a lot more important for servers than clients. Also, a
> simple API might be more desirable on the client than on the server
> (again, because of performance). For these reasons it will likely do
> more harm than good to try to use server abstractions in a client API
> or vice-versa.

I understand your point of view, but we also have to take into account
applications that need high performance for clients too.
Implementating transparent RESTful proxies for non-RESTful
applications is a common use case where you need excellent
performance, multi-threading on both sides of your application. 

FYI, we provide two client HTTP connectors (pluggable and using the
same API), one based on JDK's HttpURLConnection and another based on
Apache HTTP Client library. 

Also, in our case, you can directly set the client's output
representation reference as the server's output representation,
without reading/buffering anything. An optimized implementation of the
Restlet API could even directly move bytes from client socket to
server socket without consuming JVM memory thanks to Java's NIO.

Anyway, we didn't find the sharing of common classes between the
server-side and the client-side of the API to be an issue, it's even
the opposite. For this design, we leveraged the notion of REST uniform
interface (see our org.restlet.Uniform class) and the generic HTTP
message aspects (entity headers common to both HTTP requests and
responses). Just think about representations metadata (ETag, media
type, encoding, etc.), their are strictly the same.

Even the HTTP specification doesn't provide two separate definitions
for requests and responses depending on whether you see the
communication from the client end or from the server end of the
connection, so why redefine them twice at the API level? 

Best regards,
Jerome



 

Hi Dave,

I think we agree. HTTP clients and servers do received the same
Data but they use it in different ways. The Restlet API reuses the
same classes to model the Data exchanged but has separate classes to
process it, depending on your role in the HTTP exchange (client or
server). See Data definition in REST:
http://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm#sec_5_2_1

My point is that there's no binary separation, life is a bit more
complex here. Some artifacts can be shared between a client and server
(the data and metadata), while others have to be designed specifically
for clients or for servers. In the Restlet API, we've tried to find a
balance between both needs: reuse and specificity.

> I'm not saying JSR 311 should have separate APIs for client/server, 
> just pointing out that there are scenarios where it is desirable.

In my opinion, JSR 311 should exclusively target the server-side role.
The true challenge it to properly map between object-oriented domain
objects (POJOs) and RESTful resources and representations. This is
comparable to the mapping between POJOs and RDBMS (EJB/JPA/Hibernate)
or between POJOs and RDF graphs (Sommer).

Best regards,
Jerome

On 2/16/07, Dave Orchard <orchard@...> wrote:
>
>
> Jerome,
>
> There's a huge difference between a protocol specification  such as HTTP and an API specification for a protocol.  HTTP is the  same for both client and sender because they both see the same things on the  wire.  An API could be dramatically different based upon the needs of  clients vs services, and what kind of infrastructure is available  for use.  I'm not saying JSR 311 should have separate APIs for  client/server, just pointing out that there are scenarios where it is  desirable.
>
> Cheers,
> Dave

At the same time, on the assumption that servers often talk to remote
systems, having the ability to chain stuff across the connection is
kind of useful. In particular
 -a way to marshall failures without losing useful diagnostics can be handy
 -if the client is built around futures, state machines or some
alternative to blocking RPC/RMI as a metaphor, then you'd like it
somehow to integrate well with the server.

-steve

Just wanted to send you guys a link to PayPal's new "Name Value Pair" API.
They've obvious recognized the complexity of SOAP is not the best, but not
the REST is a better alternative. I blogged about it at [1].

OTOH, I'd be curious to know how you guys think it should have been
implemented if it were RESTful.  Thus far I believe I can mostly recognized
RESTfulness, but still don't know how to design for it.
 
-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."
[1]
http://blog.welldesignedurls.org/2007/02/16/paypals-new-name-value-pair-api/

"Mike Schinkel" <mikeschinkel@...> writes:

> Just wanted to send you guys a link to PayPal's new "Name Value Pair" API.
> They've obvious recognized the complexity of SOAP is not the best, but not
> the REST is a better alternative. I blogged about it at [1].
>
> OTOH, I'd be curious to know how you guys think it should have been
> implemented if it were RESTful.  Thus far I believe I can mostly recognized
> RESTfulness, but still don't know how to design for it.

It's similar to the JSON/RPC approach. You make an encoded call and
get the data back.

It's interesting that people are still using this pattern. It's
kinda the starting point for WS-* and XML-RPC and all those.

I don't have much of a problem with this particular pattern I have to
say. I'd prefer a proper RESTfull API with hypermedia as the engine of
application state. But this is a pragmatic alternative. If paypal are
prepared to scale this app (in my view this is the killer reason for
using REST) then it's fine. 

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Nic James Ferrier wrote:
> If paypal are prepared to scale this app (in my 
> view this is the killer reason for using REST) then it's fine. 

That comment seems contradictory.  Did I misread?

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

"Mike Schinkel" <mikeschinkel@...> writes:

> Nic James Ferrier wrote:
>> If paypal are prepared to scale this app (in my 
>> view this is the killer reason for using REST) then it's fine. 

What I mean is:

RESTfull apps scale better than anything else. If you're not using
REST you have to scale your app through more hardware and bandwidth
investment.


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

Nic James Ferrier wrote:
> > Nic James Ferrier wrote:
> >> If paypal are prepared to scale this app (in my view this is the 
> >> killer reason for using REST) then it's fine.
> 
> What I mean is:
> 
> RESTfull apps scale better than anything else. If you're not 
> using REST you have to scale your app through more hardware 
> and bandwidth investment.

Ah, I see. Still, it's a shame they didn't choose to go with something more
RESTful as I'm ure many developers will see what they did and emulate it.

-- 
-Mike Schinkel
http://www.mikeschinkel.com/blogs/
http://www.welldesignedurls.org
http://atlanta-web.org - http://t.oolicio.us
"It never ceases to amaze how many people will proactively debate away
attempts to improve the web..."

For those people who are not subscribed to the apache jcp-open mailing
list, in which apache participation in/votes on JCP proposals are
discussed, here is the apache response. At Roy's request there's going
be a name change to make it less "Java API For REST" to something less
all-embracing, I dont know what, maybe
"Java-API-to-keep-Java-Relevant-after-WS-*-failed"

Given that sun's RI will be in glassfish, there's no financial value
in keeping the TCK secret, so with any luck it will be open, and
hosted on java.net .If it is fully open, then everyone can
participate.

Justin Erenkrantz is probably going to be apache lead, with various
hangers on. Craig Russel (Tomcat) , Dims (Axis2), maybe me and dan
diephouse. I am still trying to decide how much copious free time it
merits.

-steve

-------- Original Message --------
Subject: JSR-311 : that "REST" stuff that Roy keeps carrying on about...
Date: Sat, 17 Feb 2007 06:56:46 -0500
From: Geir Magnusson Jr.
To: jcp-open

 :)

Last night, Sun informed the EC regarding the changes made to title
and package name.

I voted yes this morning with the comment :

"The ASF thanks the spec lead for making the changes to the title and
package name as noted in a mail to the EC on 2/16/07 - this was a key
requirement for us.

We'd also like to encourage the spec lead to consider creating the
software portion of the TCK as open source software, allowing
community participation in designing as well as implementing the
tests.  There is successful precedent for this, and it wouldn't
necessarily put compatibility of independent implementations nor the
spec leads ability to command support or other revenue at risk if
this path was chosen.

Finally, we strongly urge the spec lead to "utilize" rather than
"leverage" an open source development model for this JSR, to
encourage as much participation from the community as possible - the
community has a tremendous amount of experience using this
architectural model, and it behooves the spec lead to take advantage
of known best practices."

On Wed, 2007-02-14 at 22:21 +0000, Nic James Ferrier wrote:
> One would have to come up with a list of attributes of RESTfull
> systems:
> - what's the content types? 
> - does it support HEAD properly? 
> - what happens when you do methods that aren't supported? etc...
> and then apply weights to each of them. 
> Then write a client to test a webapp for each of the attributes (we
> might call them constraints /8-) and then produce a report.

I think writing a client to automate anything will be difficult for the
most important aspects of an architecture. Here is my quick list:

Ad hoc interoperability, vertical scalability
* Identifiers should fall into two overlapping classes:
** Identifiers that select a particular piece of information to
manipulate, and
** Identifiers that select a place where further data can be added (eg
POST(a) or POST(p))
* Every resource should implement as many of the architecture's
interaction patterns as makes sense. eg GET, PUT, POST, DELETE, HEAD.
** Content returned as the same document type by the same url should not
normally differ on other inputs such as cookies or basic authentication,
though personalisation can rub this up a little.
* Content types should
** Be free from verbs (except for code-on-demand), representing pure
data.
** Encode similar data schemas into the same document type
** Be standard wherever possible
** Include standard documents as sub-documents wherever appropriate
** Extend standard document types through subclassing when variation is
required
** Invent new document types when nothing out there is a good fit

Evolvability:
* Components should ignore features of a document they do not understand
* Components should avoid wildcard matches in parsing that might lead
them to interpret a feature they do not understand as if it were one
they do understand
* Components should not alter their processing depending on a version
number found in a document
* If incompatible changes occur to a document type, it should normally
be given a new document type identifier
* Components should continue to support legacy features and interface
until such time as it is known that they are no longer in use

Horizontal scalability:
* When a server does stores state due to client requests, that state is
either:
** Hidden from view, or
** Made visible as a resource that can be further retrieved and
manipulated
* Server-side state storage should be avoided when no money is changing
hands to support this storage. This can be said for sessions, pub/sub,
and other times when the server stores state either temporarily or
perminently. Paying for bandwidth almost involves funny money, but
storage can really cost you. It hurts horizontal scalability, increases
complexity, and generally makes life hard. That said, most services need
to store some state. Just don't to any more than you have to.

Benjamin.

Hmmm not sure if I'm over simplifying but in a nutshell these protocols
are just trying to repeatedly POST/PUT to a resource identified by a
unique id. I think you can just rely on PUT for idempotency and the rest
just depends on who you want to generate the id.

If the clients can generate unique ids, then why don't they just
repeatedly PUT to http://example.com/<myuniqueid> ?

If you'd rather the server "allocates" ids then
>> POST /factory
<< 201 Created
<< Location: /factory/<auniqueid>
Then then client repeatedly PUTs to
http://example.com/factory/<auniqueid>

There seems to be some worry about "reclaiming" an unused id after a
period of time, but is that really a concern? You don't really
"allocate" or "do" anything on the POST. You just make sure you never
send back the same id twice which isn't that hard. You don't even need
to keep track of what you've sent. If you're worried about the client
making an id up, you could either a) not care -- this is essentially
back to the client-generated-id case, or b) sign your ids so you can
detect a fraud.

Am I missing something?

Andrew Wahbe

On Thu, 2007-02-15 at 10:19 -0500, Mark Baker wrote:
> On 2/15/07, Elliotte Harold <elharo@...> wrote:
> > The only way to get the ideal client API is to design just a client
> API.
> > The only way to get the best serve side API is to design just a
> server
> > side API. If REST is done right, then we shouldn't need to
> coordinate
> > the two design efforts. The interfaces between the two should be
> limited
> > to HTTP.
> I agree. Moreover, I also think you generally have different design
> goals with client and server APIs. For example performance is
> normally a lot more important for servers than clients. Also, a
> simple API might be more desirable on the client than on the server
> (again, because of performance). For these reasons it will likely do
> more harm than good to try to use server abstractions in a client API
> or vice-versa.

I am of the opinion that it can be useful to share the same abstraction,
though it has to be fairly finely tuned and you may still have some
tweaks on one side or the other.

I believe I am credited with helping inspire J�r�me's writing of the
restlet framework, and I have developed a similar framework in-house for
the company I work fork. It started out as mostly an interface class for
interacting with a remote server, however we now also use it as part of
the mechanism to accept client requests. I combine it with a simplified
routes-like mechanism to locate an appropriate resource object which can
then have calls made upon it. Most of our software acts both as client
to something and server another. This is enterprise-scale REST rather
than Web-scale.

I admit it isn't perfect, but the opportunities to chain in extra
authentication mechansims and other features have proven useful. It has
also been easy to write little proxies to translate from one protcol to
another, for example from HTTP to our internal protocols. In short, I
think having a uniform interface in code has been a valuable way to
bring the architectural constraints we are looking for closer to the
developer.

Benjamin

Thanks for this. It's a fantastic list!


Benjamin Carlyle <benjamincarlyle@...> writes:

> * Every resource should implement as many of the architecture's
> interaction patterns as makes sense. eg GET, PUT, POST, DELETE,
> HEAD.

Surely this doesn't need to be tested? An application is not
non-RESTfull if it doesn't implement a method that we may think it
should. That is subjective.


> * Content types should
> ** Be free from verbs (except for code-on-demand), representing pure
> data.
> ** Encode similar data schemas into the same document type
> ** Be standard wherever possible
> ** Include standard documents as sub-documents wherever appropriate
> ** Extend standard document types through subclassing when variation is
> required
> ** Invent new document types when nothing out there is a good fit

All of these seem testable to me.


> Evolvability:
> * Components should ignore features of a document they do not understand
> * Components should avoid wildcard matches in parsing that might lead
> them to interpret a feature they do not understand as if it were one
> they do understand
> * Components should not alter their processing depending on a version
> number found in a document
> * If incompatible changes occur to a document type, it should normally
> be given a new document type identifier
> * Components should continue to support legacy features and interface
> until such time as it is known that they are no longer in use

Most of these look like client side things. It has just occured to me
that automated client testing looks very difficult.


> Horizontal scalability:
> * When a server does stores state due to client requests, that state is
> either:
> ** Hidden from view, or
> ** Made visible as a resource that can be further retrieved and
> manipulated
> * Server-side state storage should be avoided when no money is changing
> hands to support this storage. This can be said for sessions, pub/sub,
> and other times when the server stores state either temporarily or
> perminently. Paying for bandwidth almost involves funny money, but
> storage can really cost you. It hurts horizontal scalability, increases
> complexity, and generally makes life hard. That said, most services need
> to store some state. Just don't to any more than you have to.

I think this boils down to a question of not doing cookies or URL
rewriting?


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

On Sun, 2007-02-18 at 20:50 +0000, wahbedahbe wrote:
> Hmmm not sure if I'm over simplifying but in a nutshell these
> protocols
> are just trying to repeatedly POST/PUT to a resource identified by a
> unique id. I think you can just rely on PUT for idempotency and the
> rest
> just depends on who you want to generate the id.
> If the clients can generate unique ids, then why don't they just
> repeatedly PUT to http://example.com/<myuniqueid> ?

I was having this thought just last night, and I can't say I disagree :)

Just use a PUT and let the client pick a globally unique ID. The server
can then either continue using the resource the client identified in the
first place for redirect the client for to the "real" name of the
resource further interactions. I would lean towards the former.

It's an interesting perspective that essentially elminates the POST at
most once issue by eliminating POST. Do we really need our scruffy
fourth method?

> If you'd rather the server "allocates" ids then
> >> POST /factory
> << 201 Created
> << Location: /factory/<auniqueid>
> Then then client repeatedly PUTs to
> http://example.com/factory/<auniqueid>

This was one of the proposals I wrote up early in the thread, though it
still has its problems in terms of server resources needing to be
cleaned up.

> There seems to be some worry about "reclaiming" an unused id after a
> period of time, but is that really a concern? You don't really
> "allocate" or "do" anything on the POST. You just make sure you never
> send back the same id twice which isn't that hard. You don't even need
> to keep track of what you've sent. If you're worried about the client
> making an id up, you could either a) not care -- this is essentially
> back to the client-generated-id case, or b) sign your ids so you can
> detect a fraud.

This would still be an issue if you did the redirection thing, or if the
resource was destroyed soon after creation. You would need to keep both
urls around in case the client continued to send PUT requests to their
defined url. It's a horizontal scalability thing. If you need to store
information based on a client request, then you need all of the servers
in your cluster that might recieve the next request to know that
information before the next request comes in. It's statelessness between
requests, a fuzzy but important constraint in REST. Ignore it at your
peril, but most of us will need to bend it to varying degrees. The long
an the short of it is whenever and however far you bend it, make sure
you're getting paid enough to deal with the scalability issues the
bending introduces.

Let me do the concrete proposal thing again.

Problem statement: (same as before)
I have some state that I want to append to a resource. The right method
according to HTTP is POST, but if I don't get a response to my POST I
don't know whether or not to retry.

Client algorithm:
...
guid = generateCryptographicallySafeGloballyUniqueID();
// Perhaps this uri template is retrieved from a GET to what would have
// been our factory resource, or from a broader form that the user
// filled-out.
request.populateURITemplate("http://airline.example.com/ticketsales/{user}/{guid}",user,guid);
startOrResetTimer(reasonable resource state retention period, eg 2min);
try
{
retryPUT:
factory.PUT(request);
}
catch (NoResponse) // aka GatewayTimeout
{
// One of two possibilities exist. Either,
// * our PUT didn't arrive, or
// * our created resource has been destroyed already
// We try to ensure that the latter doesn't
// happen by giving up after a reasonable
// period, though we may have confidence that it won't
// be destroyed quickly and just keep retrying
goto retryPUT;
}
catch (RetentionPeriodTimeout)
{
// It is still possible that we could successfully
// send the request at this point... but it could have
// been created and destroyed again given the time we
// have taken so far. We had better give up.
}
catch (...)
{
// Normal error handling
}

If we get a 201 we know that this is the first successful request. If we
get a 200 we know that a previous request had already succeeded, but we
have successfully changed state. A 410 Gone might indicate that the
resource was created and then subsequently destroyed. Some other return
codes might mean successful delivery, eg Not Modified might play some
part. However we should probably keep things simple.

I would suggest keeping the URI ranges user-specific for security and
cross-pollentation reasons. We don't want one user going and blatting
over the uri-space and preventing other valid requests from getting
through. Client GUIDs should probably be cryptographically safe to avoid
giving away secret information.

Server responsibilities:
* Don't destroy the resource too quickly, or the client won't know for
sure whether it was created in the first place. Consider leaving a 410
in place for some time if the resource is destroyed quickly.

Benjamin

G'day,

I have taken a second stab at a RESTwiki article called "REST In Plain
English"[1]. I suspect it really needs at least a third significant stab
before it is "ready", but I would like to start soliciting feedback on
the current draft.

It attempts to be REST in practice rather than REST from first
principles. It doesn't actually go and list out REST constraints.
Instead, it tries to explain the differences between an unconstrained
architecture and a RESTful architecture from a participant or manager's
perspective.

A quick extract:
REST is a set of rules that an architecture should conform to... It
isn't surprising that an unconstrained architecture has its problems...
REST eliminates ad hoc messages and radically shifts the focus of API
development towards defining pieces of information that can be retrieved
and manipulated... The uniform interface is meant to evolve over time.

I'm interested in feedback on what is really missing from the article as
well as commentry on the content. I want it to remain precise and clear
but high-level. My focus is on architecture as a vehicle for ensuring
components can talk to each other and that various other architectural
properties such as scalability and evolvability are met.

Benjamin.
[1] http://rest.blueoxen.net/cgi-bin/wiki.pl?RestInPlainEnglish

Benjamin Carlyle wrote:
> 
> 
> On Sun, 2007-02-18 at 20:50 +0000, wahbedahbe wrote:
>  > Hmmm not sure if I'm over simplifying but in a nutshell these
>  > protocols
>  > are just trying to repeatedly POST/PUT to a resource identified by a
>  > unique id. I think you can just rely on PUT for idempotency and the
>  > rest
>  > just depends on who you want to generate the id.
>  > If the clients can generate unique ids, then why don't they just
>  > repeatedly PUT to http://example.com/ <http://example.com/><myuniqueid> ?
> 
> I was having this thought just last night, and I can't say I disagree :)
> 
> Just use a PUT and let the client pick a globally unique ID. 

that's how email works (client side generation). When this issue came up 
on atompub (for the atom:id element on creating a new member entry), it 
more or less split the working group.

Ultimately if you can't trust clients, you can't trust the IDs they 
generate (for example, duplicating or gaming atom:id is an obvious spam 
vector).

There's another point. If you are asking clients to generate uids to 
stuff into URLs, then you are breaking with the idea that URLs are 
opaque to clients. This might or might not be a problem, but it's such 
an important principle it has to asked. For example, without machine 
readable deployments of URI templates, how do I know to compose the URL

{http://example.com/}{myuniqueid}

in a way that doesn't bake in the first part?

> The server
> can then either continue using the resource the client identified in the
> first place for redirect the client for to the "real" name of the
> resource further interactions. I would lean towards the former.

If you are having to issue redirects, I think you might as well let the 
server issue the id to begin with.


> It's an interesting perspective that essentially elminates the POST at
> most once issue by eliminating POST. Do we really need our scruffy
> fourth method?

It's not really about method choice imo; it's about administrative 
control of the resource namespace. Servers are best placed to manage 
their own URIs.

cheers
Bill

Hi.

I am new to REST. A while ago I saw David Heinemeier-Hanssons
brilliant keynote at RailsConf in summer 2006 [1]. He described the
new Rails 1.2 features, including REST as a new way of programming
with Rails. After watching that video I dove deep into stuff about
REST like videos, blog entries and articles about this fascinating
topic. That way I found this wounderful group a few weeks ago. It's a
pleasure to read your posts!

Now I got stuck. Perhaps the following question is something somebody
asked before in this group, but I'm afraid I couldn't find neither the
question nor the answer within the ~8000 posts of this group.

David said in the video you should use own representations for
aggregations, states and events. He constructed an example with
persons and clubs. He asked: should persons know their clubs or should
clubs know their members? He answered, that both solutions are not
right, because it feels not good to ask a club for persons or a person
for club. Clubs shouldn't know anything about persons and persons
shouldn't know anything about clubs. He introduced a new class called
Membership and objects from that class encapsulate the knowledge of
one person and one club. He designed this litte REST system with three
representations: person, club and membership.

That looked pretty cool to me! A membership is something explicit, and
not such implicit like having a list of persons in club or a list of
clubs in person. What would be if you would have to design invalide
memberships or a description of a membership or special memberships
like V.I.P.s? That's ugly without having the class Membership, isn't it?

Okay, my world was enlightened. Everything was fine. I walked six
inches over the ground for the next few days or so.

But then I asked myself (and asked, ahem, harassed a lot of friends
and colleagues) if this could be the answer to every aggregation (and
state and event). David said it is, but he hasn't said why it is, or I
haven't heard or understand what he said.

So this is the question: would you design, in a RESTful way, every
aggregation (and state and event) with a class respectivly with a
representation?

Some minor questions:
If yes: what's with a shopping cart and products in it. What would
that aggregating representation be named?

If no: what does David meant in his keynote or what am I missing here?

Thank you very much to everyone who can show me the right way. Links
to previous posts or articles covering this issue are also very welcome.

   Bernd

[1] http://www.scribemedia.org/2006/07/09/dhh

On 2/18/07, Benjamin Carlyle <benjamincarlyle@...> wrote:
>  This was one of the proposals I wrote up early in the thread, though it
>  still has its problems in terms of server resources needing to be
>  cleaned up.

That's actually a non-problem if you design your PUT URIs well.
For example, the PUT URI could contain a time stamp. (presume you
can make them all unique, if you can't then add in a counter).
The idea is that there is nothing to store. If a PUT is attempted at
a URI with a time stamp that is too old then just reject it. No need to
store anything since the time stamp is in the URI.

Don't trust your clients? Add a hash that verifies the time stamp+counter:

  http://example.org/temporary/{timestamp}+{counter}+{hash}/

Once a PUT is successful you can redirect to the right 'final' URI.

   -joe

-- 
Joe Gregorio        http://bitworking.org

Thanks everyone again for your invaluable feedback on 'REST for the
Rest of Us' [1].  I've finally integrated most of it.  While doing so,
I realized that a REST Lexicon [2] for quick reference would be really
useful as well.

Is there such a thing I can borrow definitions from?  Attribution will
be done by links.  Any pointers/suggestions appreciated.


Cheers,

- Steve

--------------
Steve G. Bjorg
http://www.mindtouch.com
http://www.opengarden.org

[1] http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us
[2]
http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us/REST_Lexicon

"Bernd Schiffer" <schifferbernd@...> writes:

> Hi.
>
> I am new to REST. 
Welcome!

> So this is the question: would you design, in a RESTful way, every
> aggregation (and state and event) with a class respectivly with a
> representation?

I think you've been saying 'aggregation' for 'aggregation by
relationship' (aggregation does not necessarily have to be by
relationship).

But not all relationships ('aggregation' in your question) are
supposed to be exposed to outside. Rather, you should be exposing only
relationships that are worthy to be considered as a resource in your
particular context.

For example, it is OK to have a MEMBERSHIP resource which allows
consumer to manipulate MEMBERSHIP relationship. However, it may or may
not be appropriate to expose an ADDRESS resource which allows consumer
to manipulate a user's address. Instead, you could manipulate the
address through the USER resource.

REST is resource-centric. What a resource is depends on the
context on hand. There is no always nor never.

> Some minor questions:
> If yes: what's with a shopping cart and products in it. What would
> that aggregating representation be named?

The shopping cart.

Bear in mind that the shopping cart is already a name for the
relationship between goods the store has and goods you want to buy.

Hope that helps.

YS.

I've once again been impossibly busy, so everyone that was watching this 
thread has no doubt forgotten what it was all about...

I was trying to explain my REST pattern:

>>So - I promote a /symmetric/ REST point of view, with
>>active resources being dependent on each other and conveying
>>state between themselves with either GET or POST depending
>>on which party initiates the transfer.
>>
>>I do hope and believe this pattern is still REST-compatible.
>>Please read part 3 of my series 
>>(http://duncan-cragg.org/blog/post/business-functions-rest-dialogues/) 
>>for more explanation of this pattern.
>>
I'm hoping to see if 'Symmetric REST' is a clean subset of REST - i.e., 
adding more constraints, not fewer or different ones.

Symmetric REST has definitive answers to the following issues that recur 
so often on this list:

  -: The meaning (nearly said 'semantics'!) of POST
  -: Client state, cookies, and user identity
  -: Using PUT/POST/DELETE vs just using POST
  -: Queries
  -: Opaque/Transparent URIs


The essence of my pattern is that, instead of some opaque client that's 
outside of the world of resources, we see each HTTP GET or POST as being 
performed on behalf of a peer resource, and see them both as simply 
forms of state transfer between resources - one pull, the other push.


A specific case of this is shown in a form POST, the data of which has a 
content-type, but no URI! So we can't subsequently save a reference to 
the POSTed data and GET it again later. The POST is the one and only 
chance we have to see the data.

Another case in point is client state stored in Cookies. It feels like 
it should be a URI identifying the user ('s browser/machine).

When a server receives a POST, it cares who sent it and whether they are 
authorised to try and affect things on the server. Each submitter may 
have different motives and variants on things being POSTed, and the 
server has to reconcile them itself - it can't necessarily just do what 
the clients want. We have client sources wanting something, and server 
resources wanting perhaps something else.

So a POST is as much about the client as it is about the target resource 
- perhaps more so.  In a Resource-Oriented Architecture, we really 
should be dignifying POST data with a URI and talking about its valid 
content-types in the same way as we do for server resources we would GET.

A form submission, complete with cookie, is an announcement of the 
'state of the user' - the cookie /is/ like a URI and the POST body is a 
notification of their 'state' (of mind at the time).

A client is now just another 'server' with /resources/ that themselves 
perform GETs and POSTs and which can, symmetrically, be targets of GETs 
and POSTs. We may need Comet-like patterns to get this to work in a browser.

So - a resource GETs to pull the state of a peer resource, and POSTs to 
push its /own/ state to a peer.  Better still, a resource can push its 
URI (perhaps in a Content-Location: header in a request message), and 
let the target GET the content when its ready.  Adding Content-Location: 
to a request header is perhaps a little non-HTTP, but shouldn't be non-REST.

Now, all resources are active entities responsible for their own destiny 
and interact using GET/POST, or 'using REST'.


Benjamin Carlyle had some excellent things to say, as always, so I'd 
like to pick up from there:

> I haven't read your content in detail as yet, but you also seem to be
> including a pub/sub mechanism in your model. Again without knowing how
> much of this you have covered exactly, subscription also has its
> complications :)
> 
Yes - the next obvious step is to implement pub/sub: we can keep track 
of those peer resources that are interested in us, and POST to them our 
state whenever it changes.  Alternatively, we can use one of the many 
open- or long-GET patterns to receive updates.  Better still, POST or 
long-GET the /fact/ of a change, then use normal GET to fetch the new 
state, allowing normal caches to fill up and allowing lazy cacheing.

What, um, 'complications' did you have in mind?  Time out of 
subscriptions, scalability of vast numbers of subscriptions, that kind 
of thing?


>>-: Alternatively - what seems to be the subject of this thread - 
>>it may have *real-world dependency*: maybe it can't just switch 
>>to 'running' until the real world thing it models actually /is/ 
>>running! So, when it receives a direct transformation intent, 
>>it goes off and satisfies that constraint by ensuring it's 
>>ticking over in reality, and only then changes its visible 
>>state to 'running'.
> 
> I'm a SCADA guy, so this is a kind of resource that comes frequently to
> mind for me. This kind of resource can have knock-on effects also. If I
> start a fan in a chiller plant for a building I am likely to see changes
> to the resources demarcating temperature guage state. These changes slip
> between resources via the implementation of these resources,
> specifically the monitoring of changes to real world conditions.
> 
I was a SCADA guy. Nearly 30 years ago, but it's still in me blood.. =0) 
The 'feeling' of REST and declarative approaches generally is the same 
as that I used to get when designing logic circuits, and especially 
controllers, in my teenage (it's OK, I discovered girls eventually)!


>>-: Finally, the resource may be *smart*, and decide to switch to 
>>'running' because of the rule that, as long as Joe's resource is 
>>running, it should be running itself. So it spots Joe's resource 
>>running, and starts running without even being told to! That's what I 
>>was talking about in part 3 of my dialogues.
> 
> I suspect this is also the kind of resource that models most business
> functions... though I would like to cut to the specifics. I see a set of
> resources as an API to a service that expose its functionality in an
> architecturally-consistent way. Importantly, they are not services in
> their own right. They share state with each other, but this is not the
> same as communicating with each other by RESTful means. They are
> implemented with objects or with embedded database procedures. These
> implementation-level entities talk to each other. That interaction is
> what affects the service's resources.
> 
> So you have a service that is managing which other
> services/devices/functions are running in its system. It observes a
> change in one, and starts the other. The actual observation could be an
> object notifying others via an observer pattern, .. or pub/sub
> notification mechanism or by GET polling.
> 
> The systems I work with tend to have a lot of pub/sub relationships to
> trigger knock-on behaviours between services. This is necessary because
> changes to the real world are unpredictable to even the most aware
> components in the architecture. Within a service we would typicically be
> talking about the observer pattern. ..
> 

Now - this is where you get to the heart of the issue (excellent 
response! thanks): I /am/ suggesting that our in-process programs should 
be event-driven, and use the observer pattern as the only interaction 
mode between domain objects. Objects will have open state and no methods 
- apart from GET and POST. So, OK, they're not really objects in the 
traditional sense. This is where we switch from imperative to 
declarative models. We can program in declarative rules, triggered by 
events over state. Then distributing such a program is simply 'draw a 
dividing line through and drop HTTP - used symmetric-RESTfully - in the 
middle'! Needless to say, SEDA would be a good fit to this, server-side..


Quickly on the remaining points (this has turned out to be too long 
again) - URIs: opaque - if you want content and content syntax, it goes 
in the body - end of discussion =0) So Queries: POST-redirect pattern. 
PUT/DELETE: if you want imperative stuff like that, stick it in a 
special 'Builder' content type and POST it instead - you have much freer 
reign to do all sorts of other hypermedia manipulations anyway like 
that, plus it prevents people seeing REST as = CRUD and expecting a 
database... [sorry to any recent Rails arrivals who are bemused by all 
this!]


OK - I've gone on enough.   Any comments (even "wha'???") are welcome. 
In fact, especially "wha'???" - it helps me hone my presentation! =0)

Cheers!

Duncan

PS - Joe: did you get my email? Anyway, thanks for the good stuff at 
http://wellformedweb.org/story/1. What do you /now/ think about the Well 
Formed Web?

_________________________________
Duncan Cragg
http://duncan-cragg.org/blog/

I'm getting a gut feel that Atom (both the format and the publishing 
protocol) is going to be very useful and used for
many other things other than blog publishing.  It has some very
interesting characteristics that make it a good fit for various
integration scenarios, amongst other things.

Philosophically, it can almost be perceived as a simpler, easier, REST-
oriented alternative to SOAP.   We may finally have something to counter the 
dirtiness that is SOAP, since Atom can be a very good enveloping mechanism.

Most of the current hype about Atom is about blogs.  Which might not be a bad 

thing, since it will keep other uses under the radar and in stealth mode 
(from the evil Corporate IT types who don't know any better ;-) ), till we 
have some "but it just works" deployments to show off.

I'm curious if anyone else is using/has used/ is considering ATOM and/or APP 
for other purposes, especially in the integration space?



Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

"REST replacement for SOAP"... ha ... true, and sad, because for all
its ambitions APP is just another envelope for documents. It's not
much of an improvement over doc style SOAP. Just being RESTful isn't
enough to encourage widespread adoption. Yay: there's no verb in the
message. Yay, they obey HTTP method semantics. Apart from that they
both wrap a document in an envelope.

As long as servers and clients have to agree ahead of time on complete
document semantics they're forcing one another to lock in code at
development time. But the aspect of the web that promotes independent
evolution is the dialog that goes on between server and agent -- in
particular forms. Servers tell agents how to compose messages; they
don't agree on message formats ahead of time.

I don't think APP is a failure. I'm just saying you won't see
significantly more "programmable web" using APP than you would have
with SOAP.

Don't you start me talking!


Hugh



On 2/20/07, Andrzej Jan Taramina <andrzej@...> wrote:
> I'm getting a gut feel that Atom (both the format and the publishing
> protocol) is going to be very useful and used for
> many other things other than blog publishing.  It has some very
> interesting characteristics that make it a good fit for various
> integration scenarios, amongst other things.
>
> Philosophically, it can almost be perceived as a simpler, easier, REST-
> oriented alternative to SOAP.   We may finally have something to counter the
> dirtiness that is SOAP, since Atom can be a very good enveloping mechanism.
>
> Most of the current hype about Atom is about blogs.  Which might not be a bad
>
> thing, since it will keep other uses under the radar and in stealth mode
> (from the evil Corporate IT types who don't know any better ;-) ), till we
> have some "but it just works" deployments to show off.
>
> I'm curious if anyone else is using/has used/ is considering ATOM and/or APP
> for other purposes, especially in the integration space?
>
>
>
> Andrzej Jan Taramina
> Chaeron Corporation: Enterprise System Solutions
> http://www.chaeron.com
>
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Hugh Winkler
Wellstorm Development

http://www.wellstorm.com/
+1 512 694 4795 mobile (preferred)
+1 512 264 3998 office

On Tue, Feb 20, 2007 at 10:50:10AM -0500, Andrzej Jan Taramina wrote:
> I'm curious if anyone else is using/has used/ is considering ATOM
> and/or APP for other purposes, especially in the integration space?

http://2006.xmlconference.org/programme/presentations/202.html

I wrote to the author to inquire if there were more detailed notes or
an audio or video recording available... unfortunately, there isn't.


-- 

Paul Winkler
http://www.slinkp.com

Definitely.  Just check out Yahoo Pipes or any of the Google (near)APP services.

On 2/20/07, Andrzej Jan Taramina <andrzej@...> wrote:
> I'm getting a gut feel that Atom (both the format and the publishing
> protocol) is going to be very useful and used for
> many other things other than blog publishing.  It has some very
> interesting characteristics that make it a good fit for various
> integration scenarios, amongst other things.
>
> Philosophically, it can almost be perceived as a simpler, easier, REST-
> oriented alternative to SOAP.   We may finally have something to counter the
> dirtiness that is SOAP, since Atom can be a very good enveloping mechanism.
>
> Most of the current hype about Atom is about blogs.  Which might not be a bad
>
> thing, since it will keep other uses under the radar and in stealth mode
> (from the evil Corporate IT types who don't know any better ;-) ), till we
> have some "but it just works" deployments to show off.
>
> I'm curious if anyone else is using/has used/ is considering ATOM and/or APP
> for other purposes, especially in the integration space?
>
>
>
> Andrzej Jan Taramina
> Chaeron Corporation: Enterprise System Solutions
> http://www.chaeron.com
>
>
>
>
> Yahoo! Groups Links
>
>
>
>


-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

On Feb 20, 2007, at 5:11 PM, Hugh Winkler wrote:

> I don't think APP is a failure. I'm just saying you won't see
> significantly more "programmable web" using APP than you would have
> with SOAP.

I beg to differ -- REST + APP just means some more constraints, which  
IMO is a good thing for increasing understanding, which furthers the  
"programmable Web".

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

 
On Tuesday, February 20, 2007, at 04:52PM, "Andrzej Jan Taramina" <andrzej@...> wrote:

>I'm curious if anyone else is using/has used/ is considering ATOM and/or APP 
>for other purposes, especially in the integration space?

I spent most of my non-working hours and even some of the working hours during the
last year on this topic.

IMHO, Atom/APP can be for the Enterprise Space (large scale, machine-2-machine
oriented systems) what HTML is for the human oriented Web. With HTTP alone, the
design space is too unconstrained for an average developer/designer to get real work
done but with the introduction of Atom/APP (and a core set of extensions) design becomes
manageable for them.

Yes, definitely - there seems to be a bright future for that marriage.

Jan


>
>
>Andrzej Jan Taramina
>Chaeron Corporation: Enterprise System Solutions
>http://www.chaeron.com
>
>
>
> 
>Yahoo! Groups Links
>
>
>
>
>

On 2/20/07, Stefan Tilkov <stefan.tilkov@...> wrote:
> On Feb 20, 2007, at 5:11 PM, Hugh Winkler wrote:
>
> > I don't think APP is a failure. I'm just saying you won't see
> > significantly more "programmable web" using APP than you would have
> > with SOAP.
>
> I beg to differ -- REST + APP just means some more constraints, which
> IMO is a good thing for increasing understanding, which furthers the
> "programmable Web".
>

I guess we could find some extra constraints in APP. maybe the absence
of a verb in the message definition is the major one. Good on them.

I cannot figure out why APP needs an envelope at all. It makes sense
for web sites exposing feeds with > 1 entry to use a format that rolls
up each items metainfo with the item itself -- call that a list of
entries. That's not APP; it's just serving up feeds.

But when I'm POSTing or PUTting content, I could just POST/PUT the
html/xhtml/text/whatever representation directly to the content URI.
Entity headers could capture anything they currently model in an
<entry>. APP could simply be a list of entity header definitions. But
they've forced implementors to model something called an <entry> which
just wraps the real content. Then there's this indirection to get to
the real content.

In that respect, APP did not enhance my understanding.

Hugh

Funny, I'm just now in the process of formulating a simple  
demonstration of how to manage bibliographic metadata with APP. Has  
anyone else documented their use of APP for non-blogging applications  
anywhere? I have run across gdata and pipes--what are the other  
prominent implementations?

//Ed

Hugh:

> "REST replacement for SOAP"... ha ... true, and sad, because for all
> its ambitions APP is just another envelope for documents. It's not
> much of an improvement over doc style SOAP. Just being RESTful isn't
> enough to encourage widespread adoption. Yay: there's no verb in the
> message. Yay, they obey HTTP method semantics. Apart from that they
> both wrap a document in an envelope.

I'm not sure I agree with your carte blanche reasoning that an envelope is a 
bad idea.  Having a simple enveloping structure can help divorce transmission 
semantics from document semantics in a nice way.  SOAP is just too 
complicated, too rigid and too tied to other crap like XSDs, WSDLs and the 
like, and fosters RPC thinking more than not.  

The Atom format looks like a much nicer, lightweight framework for 
information publishing and consuming.  And the APP provides behavioural rules 
on how to transport that format over HTTP, basically providing an off-the-
shelf, standardized REST mechanism, which is not a bad thing.

> As long as servers and clients have to agree ahead of time on complete
> document semantics they're forcing one another to lock in code at
> development time. 

I don't think we're going to see a resolution of that semantic agreement in 
my lifetime.  At least not that is understandable and implementable by mere 
mortals (most semantic web initiatives are not either).  And I see nothing 
wrong with solving businsess problems by designing and formalizing document 
semantics between involved parties in the meantime.  Better than not solving 
the problems.  A good example is the  Integrated Health Record holy grail 
that most western countries are desperate to move towards.  You're not going 
to resolve the semantic issues in that arena using automated approaches any 
time soon.  T

> But the aspect of the web that promotes independent
> evolution is the dialog that goes on between server and agent -- in
> particular forms. Servers tell agents how to compose messages; they
> don't agree on message formats ahead of time.

You know, my inquiry was to do with integration schenarios, machine to 
machine, between existing systems for the most part.  Don't much care about 
the web as you define it above, in the context of what I'm working on of 
course, except as a global transmission and connectivity mesh.

> I don't think APP is a failure. I'm just saying you won't see
> significantly more "programmable web" using APP than you would have
> with SOAP.

Like I said, I'm interested in more classic integration scenarios and not the 
concept of a "programmable web", and that is the context within which I want 
to discuss Atom and APP applicability.

> Don't you start me talking!

Why not?  That was the intent of my post.  To initiate a discussion of the 
merits and possibilities of using Atom and APP for things other than blogs. 
;-)



Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

Jan:

> I spent most of my non-working hours and even some of the working hours
> during the last year on this topic. 

I knew I wasn't alone in this thinking!

> IMHO, Atom/APP can be for the Enterprise Space (large scale, machine-2-machine
> oriented systems) what HTML is for the human oriented Web. With HTTP alone,
> the design space is too unconstrained for an average developer/designer to get
> real work done but with the introduction of Atom/APP (and a core set of
> extensions) design becomes manageable for them.

Are there any references, documents, discussion, examples of such usage 
and/or extensions that you can point me at?

> Yes, definitely - there seems to be a bright future for that marriage.

Super!

Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

> Definitely.  Just check out Yahoo Pipes or any of the Google (near)APP
> services.

I've been meaning to check out Pipes for a while....but what I'm thinking of 
is more industry-specific integration scenarios.  Retail,  Manufacturing,  
Healthcare, Government, Aerospace and other uses for integration purposes.

Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

Hugh:

> I think we will. The technique we end up using will come from some
> effort like microformats. It probably won't have a ton to do with OWL.
> Some people will just tag elements in forms and declare what
> "author-name" means, and off we go.

Sure, for specific problem areas or needs.  ATOM/RSS did just that for blog 
publishing and aggregation for the most part, at least at some conceptual 
level.

My comment was more about overall semantics, that are not tied to a 
particular application or solution segment.  Where any arbitrary server and 
client could just decide to communicate and have it happen automagically. I 
just don't see that happening any time soon.


Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

oh, and...

> On 2/20/07, Andrzej Jan Taramina <andrzej@...> wrote:
>
> > You know, my inquiry was to do with integration schenarios, machine to
> > machine,...

I'm talking about machine-tot-machine integration scenarios, but
perhaps not the painful "classic" ones. New ones that are less
painful. ;)

Hugh

On 2/20/07, Andrzej Jan Taramina <andrzej@...> wrote:

> I don't think we're going to see a resolution of that semantic agreement in
> my lifetime.

I think we will. The technique we end up using will come from some
effort like microformats. It probably won't have a ton to do with OWL.
Some people will just tag elements in forms and declare what
"author-name" means, and off we go.

>
> > But the aspect of the web that promotes independent
> > evolution is the dialog that goes on between server and agent -- in
> > particular forms. Servers tell agents how to compose messages; they
> > don't agree on message formats ahead of time.
>
> You know, my inquiry was to do with integration schenarios, machine to
> machine,... I'm interested in more classic integration scenarios and not the
> concept of a "programmable web", and that is the context within which I want
> to discuss Atom and APP applicability.
>

I think you will find APP enterprisey enough for those scenarios...

Hugh

On 2/20/07, Andrzej Jan Taramina <andrzej@...> wrote:
> Hugh:
>
> > I think we will. The technique we end up using will come from some
> > effort like microformats. It probably won't have a ton to do with OWL.
> > Some people will just tag elements in forms and declare what
> > "author-name" means, and off we go.
>
> Sure, for specific problem areas or needs.  ATOM/RSS did just that for blog
> publishing and aggregation for the most part, at least at some conceptual
> level.

Agreed. You could extend the APP work to define how to tag form elements.

>
> My comment was more about overall semantics, that are not tied to a
> particular application or solution segment.  Where any arbitrary server and
> client could just decide to communicate and have it happen automagically. I
> just don't see that happening any time soon.
>

I don't think it will happen in a big bang either. It will happen in
particular solution segments first. Then there will be some bleedover.
Then certain winners will emerge from the tagwars.

Hugh

> I don't think it will happen in a big bang either. It will happen in
> particular solution segments first. Then there will be some bleedover.
> Then certain winners will emerge from the tagwars.

I'm with you on that. We'll see data formats and semantic standards in 
disparate industry segments.  What I doubt is that will then somehow 
amalgamate together into one massive glop of semantic goodness, where anyone 
can talk to anyone, automagically.  Just don't see it.

Love the "tagwars" term.  LOL

One of the things that is attractive about using Atom/APP for enterprise 
integration (specifically between disparate enterprises, where one can't 
dictate to the other) is it's very simplicity. Easy to implement and get a 
prototype running to show value.  Then not too hard to extend to provide more 
ROI.  I've always preferred evolutionary approaches to tough integration 
issues.  Crawl, Walk, Run.  

If you believe the WS-GLOP vendors, they'll get you to hypersonic, 
interstellar speed, skipping the more prosaic crawl/walk/run stages. Problem 
is, the only thing that shows that kind of exponential path in that scenario 
is the vendor's bank account. ;-)

Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com

On 20.02.2007, at 20:37, Andrzej Jan Taramina wrote:

>> Definitely.  Just check out Yahoo Pipes or any of the Google (near) 
>> APP
>> services.
>
> I've been meaning to check out Pipes for a while....

I am having applying-Atom/APP-to-ETL on my list of stuff to think  
about....
Yahoo Pipes are wonderfully near that, in a sense.

Jan

Hi all,

Apologies for the cross-posting, but (IMHO) this is a pretty  
significant development for both communities:

	RESTful Rails Development
	by Ralf Wirdemann & Thomas Baustert
	http://www.b-simple.de/documents

As most of you know, Rails 1.2 made a pretty dramatic shift towards  
RESTful web applications.  This document (recently translated from  
the German) is the definitive summary of what REST looks like from  
the perspective of Ruby on Rails -- which I suspect is where many new  
programmers are going to first experience REST!

So, I encourage y'all to check it out.  And, if you find areas where  
you think Rails isn't being RESTful enough, let me know and I'll  
collate the feedback for Mr. Rails, David H. (though I think he's on  
at least one of these lists himself).

-- Ernie P.

RESTful Rails Development PDF Released

http://www.rubyinside.com/restful-rails-development-pdf- 
released-392.html

POST BY PETER COOPER

A month ago I reported on the release of a PDF (in German) covering  
Rails' REST abilities by Ralf Wirdemann and Thomas Baustert (the  
authors of the first German Rails book, "Rapid Web Development mit  
Ruby on Rails"). With the help of Florian G�rsdorf and Adam Groves,  
they've produced a fine English translation titled "RESTful Rails  
Development". It's still free (although donations are accepted).

It's only about thirty pages long, but in that space it packs in a  
lot of information about Rails and REST, including REST routing,  
URLs, view techniques, path methods, and how to nest resources. If,  
like me, you're a Rails developer who's pretty savvy at the 1.0 level  
but haven't made the leap into the world of REST, it's a great primer.

On Tue, 2007-02-20 at 10:50 -0500, Andrzej Jan Taramina wrote:
> I'm getting a gut feel that Atom (both the format and the publishing 
> protocol) is going to be very useful and used for
> many other things other than blog publishing. It has some very
> interesting characteristics that make it a good fit for various
> integration scenarios, amongst other things.
> 
> Philosophically, it can almost be perceived as a simpler, easier,
> REST-
> oriented alternative to SOAP. We may finally have something to counter
> the 
> dirtiness that is SOAP, since Atom can be a very good enveloping
> mechanism.

HTTP is REST's current alternative to SOAP
+enough-WSDL-to-make-SOAP-do-something-useful. Atom is more like REST's
(someone's?) alternative to RDF. That is to say, it compliments a
growing family of standard document types that can be included in each
other, and can be extended for domain-specific uses without inventing a
whole new vocabulary.

RDF builds an abstract metamodel and expects vocabularies to fill the
rest of the gaps. Successful formats to date have taken a different
approach of defining vocabulary and document structure together. XML
appears to be a good tool in defining these document types. It allows
other XML documents to be easily included as sub-documents. It allows
existing document types to be extended. Combined with mime, it even has
a means to be explicit about the extension. I might define an
industry-specific application/pids+atom+xml document type that could be
interpreted purely as atom, but also has special features and vocabulary
that can be handled by parsers aware of the relevant extensions.

I see the aggregation and sub-classing features of XML as the core of
the semantic web going forwards. I think this is a more fully-featured
way of representing data than rigid RDF. Perhaps my main concern going
forwards is the modern propensity to try and replace MIME with URIs. If
I have an xml uri of http://w3c.org/xml and want to subclass it my url
would likely look something like <http://wrsa.com.au/something>. In this
case it is difficult for parsers to know that they can treat my document
type as xml for the purpose of running xpath queries. I think mime and
URIs both have their problems, but I think the problems with URIs are
more terminal when it comes to building a real semantic web.

Benjamin.

Andrzej Jan Taramina wrote:
> 
> 
> I'm getting a gut feel that Atom (both the format and the publishing
> protocol) is going to be very useful and used for
> many other things other than blog publishing. It has some very
> interesting characteristics that make it a good fit for various
> integration scenarios, amongst other things.
> 
> Philosophically, it can almost be perceived as a simpler, easier, REST-
> oriented alternative to SOAP. 

The format yes, and I've been saying this for some time. I expect SOAP 
stacks to start supporting Atom envelopes at some point, and then it 
will be game over.


> I'm curious if anyone else is using/has used/ is considering ATOM and/or 
> APP
> for other purposes, especially in the integration space?

Here you go:

Example:
-----------

[[[
<atom:entry
xmlns:iam="http://example.org/Schemas/Envelope"
xmlns:event="http://example.org/event/"
xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Envelope Seen</atom:title>
<atom:link 
href="http://example.org/mid/000001103A48103500C000A8002E000A4E0E125C" 
  /> 
<atom:id>http://example.org/BizTalkInChannel/831bf016fad89f64f8411bb3c89a6ccb</atom:id>
<atom:updated>2007-01-20T12:15:09Z</atom:updated>
<atom:summary>Envelope seen on BT-IN channel</atom:summary> 
<event:EventSource>http://example.org/channel/in/BizTalkInChannel</event:EventSource>
<event:EventLevel>http://example.org/event/level/info</event:EventLevel>
<atom:category term="envelope" scheme="http://example.org/cat/"/>
   <atom:category term="event" scheme="http://example.org/cat/"/>
   <atom:content type="text/xml">
   ...
   </atom:content>
</atom:entry>
]]]

The Atom entry elements are populated as follows :

     * atom:title: not important for processing, can appear in monitoring UI
     * atom:link: not important for processing, provides a link to the 
event on the source system (this might result in a 404)
     * atom:id: unique identifier for the event. Important for duplicate 
detection.
     * atom:updated: the time the event was created at source
     * atom:summary: not important for processing, can appear in 
monitoring UI, might be useful in describing a system event.
     * atom:category: the 'term' attribute indicates the event type if 
the "scheme" attribute is 'http://example.org/cat/'. Other schemes are 
not defined.

In addition, two extension elements are inserted into the entry

     * event:EventSource: provides a URI that names the source of the Event.
     * event:EventLevel:  provides a URI that indcates the 
level/severity of the event.


========
Event Levels and Types
========

Event Levels
---------

The level of an event is provided in the event:EventLevel extension 
element. Levels in the element take the form of URIs as follows:

http://example.org/event/{LEVEL}

The defined levels are

     * "trace": for testing
     * "debug": a debug message
     * "info": informative; also the default level for a message event
     * "warn": a warning, typically used in system events
     * "error": a error, typically used in system events
     * "critical": a severe event, typically used in system events

Event Types
-----------

Use of atom:category

The type of an event is provided in the atom:category element. Types use 
the 'scheme' and 'term' attributes. The 'scheme' attribute for a type is

http://example.org/cat/

Categorisation of events
------------

An event entry contains 2 such atom:categories.

First, all event entries contain an atom:category stating that they are 
a monitoring event, using a "term" attribute value of 'event' as follows:

<atom:category term="event" scheme="http://example.org/cat/"/>

Second, events are categorised as either system or mesage types, using 
"term" attributes value of 'system' and 'envelope' respectively:

     * System event:

<atom:category term="system" scheme="http://example.org/cat/"/>

     * Message event:

<atom:category term="envelope" scheme="http://example.org/cat/"/>

Benjamin Carlyle wrote:

> HTTP is REST's current alternative to SOAP
> +enough-WSDL-to-make-SOAP-do-something-useful.

Except that sending a HTTP envelope over XMPP is awkward. Atom travels 
over both, trivially for entries (feeds are more tied to HTTP than first 
meets the eye). And being XML it's structurally closer to SOAP; so it's 
les of a cognitive leap than going back to MIME. Anyone strategically 
invested in SOAP will be able to spin for Atom support to complement  a 
REST checkbox.

There are general problems with using XML as an envelope insofar as 
embedding payloads phsyically inside elements can result in all kinds of 
suckage - look at the half-decade of back and forth that has resulted in 
mtom and the pita that xml dsig has proven to be. I'm not sure 
MIME+octets isn't a superior packaging technology if packaging is what 
you need.


"It's not much of an improvement over doc style SOAP. Just being RESTful 
isn't enough to encourage widespread adoption. Yay: there's no verb in 
the message. Yay, they obey HTTP method semantics. Apart from that they
both wrap a document in an envelope. As long as servers and clients have 
to agree ahead of time on complete document semantics they're forcing 
one another to lock in code at development time"

I see Hugh is beating up on APP again. Hopefully we'll see him on the WG 
for last call "adding future business value". The last part by the way 
about complete document semantics simply isn't true if your document 
semantics are based on model theoretic semantics - the agents 
communities have been slinging documents back and forth for years 
without been tied to runtimes. It's just that programming to a model 
theory is esoteric compared to switch-on-type; programmers generally 
won't roll with it.

But I'll say this - the first thing to do here is compare and contrast 
the minimal Atom document with SOAP's before trashing Atom. I did the 
minimal SOAP envelope years ago and that strongly influenced a 
professional commitment not to deploy on it for clients.  Atom at least 
makes you say something.


  Atom is more like REST's
> (someone's?) alternative to RDF. 

RDF has characteristics that make it better than Atom (or any such 
XML/XHTML format) as an interlingua, but isn't quite structured enough 
as a format. That means to support RDF you tend to end up interfering 
with backend application storage to support the flexibility (IME). You 
can sink a lot of money doing that. Because Atom is less flexible it's 
easier to tie down wrt OO domain and relational backends. The only 
highly generic thing you need to support across domain types are tags, 
and there are some decent many 2 many table models you can use for that now.


> That is to say, it compliments a
> growing family of standard document types that can be included in each
> other, and can be extended for domain-specific uses without inventing a
> whole new vocabulary.
> 
> RDF builds an abstract metamodel and expects vocabularies to fill the
> rest of the gaps. Successful formats to date have taken a different
> approach of defining vocabulary and document structure together. 

I would add also that successful formats have left format semantics in 
code rather than using declarative/model techniques. Elliotte has 
historically had a good basic stance on why this gets deployed over 
shared formal _models_.

> I see the aggregation and sub-classing features of XML as the core of
> the semantic web going forwards. I think this is a more fully-featured
> way of representing data than rigid RDF. 

I'm not so sure. I think linking and tagging are the way forward, and 
the person who persuades people to go with prefix conventions for tag 
labels instead of full URIs as RDF/semweb does, will win. No-one uses 
"dc:" in XML for anything other than Dublin core.

cheers
Bill

On 2/20/07, Bill de hOra <bill@...> wrote:

> "It's not much of an improvement over doc style SOAP. Just being RESTful
> isn't enough to encourage widespread adoption. Yay: there's no verb in
> the message. Yay, they obey HTTP method semantics. Apart from that they
> both wrap a document in an envelope. As long as servers and clients have
> to agree ahead of time on complete document semantics they're forcing
> one another to lock in code at development time"
>
> I see Hugh is beating up on APP again. Hopefully we'll see him on the WG
> for last call "adding future business value".

I guess I am beating up on it, and unfairly. I'm raising topics here,
not on Atompub, because it's late in the APP cycle, the forms idea is
not baked, and the envelope thing might have been a good issue to
raise two years ago.

Unfairly, because it's like I've been scolding the dog for doing a bad
job mowing the yard (an old Far Side cartoon). APP is going to work
great for blogging clients, and for GData which will be widely
adopted.

>The last part by the way
> about complete document semantics simply isn't true if your document
> semantics are based on model theoretic semantics - the agents
> communities have been slinging documents back and forth for years
> without been tied to runtimes. It's just that programming to a model
> theory is esoteric compared to switch-on-type; programmers generally
> won't roll with it.
>

Well, yeah. We really need to find a way to make it practical to do
reasoning over these tags. It's hard because: there are lots of
definitions, the definitions are not centrally located, and even if
you get them all in one place, reasoning over them is a massive
program in itself. So I think to make it practical, programs have to
call a service to do it for them.

If we don't address that issue, web services will be stuck forever.
Each integration will be painful and time consuming. As now.

> But I'll say this - the first thing to do here is compare and contrast
> the minimal Atom document with SOAP's before trashing Atom. I did the
> minimal SOAP envelope years ago and that strongly influenced a
> professional commitment not to deploy on it for clients.  Atom at least
> makes you say something.
>

Fair enough.

>
>   Atom is more like REST's
> > (someone's?) alternative to RDF.
>
> RDF has characteristics that make it better than Atom (or any such
> XML/XHTML format) as an interlingua, but isn't quite structured enough
> as a format. That means to support RDF you tend to end up interfering
> with backend application storage to support the flexibility (IME). You
> can sink a lot of money doing that. Because Atom is less flexible it's
> easier to tie down wrt OO domain and relational backends. The only
> highly generic thing you need to support across domain types are tags,
> and there are some decent many 2 many table models you can use for that now.
>
>
> > That is to say, it compliments a
> > growing family of standard document types that can be included in each
> > other, and can be extended for domain-specific uses without inventing a
> > whole new vocabulary.
> >
> > RDF builds an abstract metamodel and expects vocabularies to fill the
> > rest of the gaps. Successful formats to date have taken a different
> > approach of defining vocabulary and document structure together.
>
> I would add also that successful formats have left format semantics in
> code rather than using declarative/model techniques. Elliotte has
> historically had a good basic stance on why this gets deployed over
> shared formal _models_.
>
> > I see the aggregation and sub-classing features of XML as the core of
> > the semantic web going forwards. I think this is a more fully-featured
> > way of representing data than rigid RDF.
>
> I'm not so sure. I think linking and tagging are the way forward, and
> the person who persuades people to go with prefix conventions for tag
> labels instead of full URIs as RDF/semweb does, will win.
>No-one uses
> "dc:" in XML for anything other than Dublin core.
>

Yes, the web is voting, and they are not even using prefixes, much
less URIs or RDF.

> cheers
> Bill
>

On 20 Feb 2007, at 21:58, Benjamin Carlyle wrote:

> On Tue, 2007-02-20 at 10:50 -0500, Andrzej Jan Taramina wrote:
> > I'm getting a gut feel that Atom (both the format and the publishing
> > protocol) is going to be very useful and used for
> > many other things other than blog publishing. It has some very
> > interesting characteristics that make it a good fit for various
> > integration scenarios, amongst other things.
> >
> > Philosophically, it can almost be perceived as a simpler, easier,
> > REST-
> > oriented alternative to SOAP. We may finally have something to  
> counter
> > the
> > dirtiness that is SOAP, since Atom can be a very good enveloping
> > mechanism.
>
> HTTP is REST's current alternative to SOAP
> +enough-WSDL-to-make-SOAP-do-something-useful. Atom is more like  
> REST's
> (someone's?) alternative to RDF. That is to say, it compliments a
> growing family of standard document types that can be included in each
> other, and can be extended for domain-specific uses without  
> inventing a
> whole new vocabulary.

Nonsense.

APP is just a way to publish content. It is a simpler version of WebDAV.
See  http://blogs.sun.com/bblfish/entry/what_atom_is_all_about

You can publish RDF using APP, just as you can publish RDF using WebDAV.

You don't even have to wrap what you publish using atom. See section 5.3
http://bitworking.org/projects/atom/draft-ietf-atompub- 
protocol-13.html#rfc.section.5.3

And neither does the server have to wrap what he receives in atom.

Furthermore one can give a very good RDF ontology of Atom.

Atom Owl Ontology:
http://bblfish.net/work/atom-owl/2006-06-06/AtomOwl.html

which one can then use to query information source, such as the  
Roller blog engine

SPARQLing Roller:
http://blogs.sun.com/bblfish/entry/sparqling_roller


> RDF builds an abstract metamodel and expects vocabularies to fill the
> rest of the gaps. Successful formats to date have taken a different
> approach of defining vocabulary and document structure together. XML
> appears to be a good tool in defining these document types. It allows
> other XML documents to be easily included as sub-documents. It allows
> existing document types to be extended. Combined with mime, it even  
> has
> a means to be explicit about the extension. I might define an
> industry-specific application/pids+atom+xml document type that  
> could be
> interpreted purely as atom, but also has special features and  
> vocabulary
> that can be handled by parsers aware of the relevant extensions.
Yes, and that is the big problem with trying to use syntax to  
exchange data. You end up having to do double the amount of work  
other people have to do. Not only do you have to model the types of  
objects that exist and the way they relate to each other, you also  
have to find an arbitrary tree structure to fit them it.

All XML Roads Lead to RDF:
http://blogs.sun.com/bblfish/entry/how_applying_xml_to_data

>
> I see the aggregation and sub-classing features of XML as the core of
> the semantic web going forwards. I think this is a more fully-featured
> way of representing data than rigid RDF.

No, it is xml that is rigid.
See Crystalising RDF
http://blogs.sun.com/bblfish/entry/crystalizing_rdf

> Perhaps my main concern going
> forwards is the modern propensity to try and replace MIME with  
> URIs. If
> I have an xml uri of http://w3c.org/xml and want to subclass it my url
> would likely look something like <http://wrsa.com.au/something>. In  
> this
> case it is difficult for parsers to know that they can treat my  
> document
> type as xml for the purpose of running xpath queries. I think mime and
> URIs both have their problems, but I think the problems with URIs are
> more terminal when it comes to building a real semantic web.


>
> Benjamin.
>
>
>
> 

Hugh Winkler wrote:
> On 2/20/07, Bill de hOra <bill@...> wrote:

> 
>> The last part by the way
>> about complete document semantics simply isn't true if your document
>> semantics are based on model theoretic semantics - the agents
>> communities have been slinging documents back and forth for years
>> without been tied to runtimes. It's just that programming to a model
>> theory is esoteric compared to switch-on-type; programmers generally
>> won't roll with it.
>>
> 
> Well, yeah. We really need to find a way to make it practical to do
> reasoning over these tags. It's hard because: there are lots of
> definitions, the definitions are not centrally located, and even if
> you get them all in one place, reasoning over them is a massive
> program in itself. So I think to make it practical, programs have to
> call a service to do it for them.

No argument there. I'd love to read a nutshell analysis as to why people 
aren't falling over themselves for those kinds of technologies (kr, 
rules, agents, semweb) - they directly address multi-billion dollar 
issues in the industry (specifically integration and change resilience). 
  I've always seem application protocols as the "software agent" 
equivalent of grunting.

cheers
Bill

On Feb 20, 2007, at 5:53 PM, Henry Story wrote:
> You don't even have to wrap what you publish using atom. See  
> section 5.3
> http://bitworking.org/projects/atom/draft-ietf-atompub-
> protocol-13.html#rfc.section.5.3

You mean like when you are posting media resources? [1]

> And neither does the server have to wrap what he receives in atom.

When posting media resources the app server MUST respond with a link  
to the media link entry which is a URI for an atom:entry. Perhaps I'm  
missing what you mean by 'wrap'?

//Ed

[1] http://bitworking.org/projects/atom/draft-ietf-atompub- 
protocol-13.html#media-link-entries

On 2/20/07, Bill de hOra <bill@...> wrote:
> Andrzej Jan Taramina wrote:
> >
> >
> > I'm getting a gut feel that Atom (both the format and the publishing
> > protocol) is going to be very useful and used for
> > many other things other than blog publishing. It has some very
> > interesting characteristics that make it a good fit for various
> > integration scenarios, amongst other things.
> >
> > Philosophically, it can almost be perceived as a simpler, easier, REST-
> > oriented alternative to SOAP.
>
> The format yes, and I've been saying this for some time. I expect SOAP
> stacks to start supporting Atom envelopes at some point, and then it
> will be game over.
>
>
> > I'm curious if anyone else is using/has used/ is considering ATOM and/or
> > APP
> > for other purposes, especially in the integration space?
>
> Here you go:
>
> Example:
> -----------
>
> [[[
> <atom:entry
> xmlns:iam="http://example.org/Schemas/Envelope"
> xmlns:event="http://example.org/event/"
> xmlns:atom="http://www.w3.org/2005/Atom">
> <atom:title>Envelope Seen</atom:title>
> <atom:link
> href="http://example.org/mid/000001103A48103500C000A8002E000A4E0E125C"
>   />
> <atom:id>http://example.org/BizTalkInChannel/831bf016fad89f64f8411bb3c89a6ccb</atom:id>
> <atom:updated>2007-01-20T12:15:09Z</atom:updated>
> <atom:summary>Envelope seen on BT-IN channel</atom:summary>
> <event:EventSource>http://example.org/channel/in/BizTalkInChannel</event:EventSource>
> <event:EventLevel>http://example.org/event/level/info</event:EventLevel>
> <atom:category term="envelope" scheme="http://example.org/cat/"/>
>    <atom:category term="event" scheme="http://example.org/cat/"/>
>    <atom:content type="text/xml">
>    ...
>    </atom:content>
> </atom:entry>
> ]]]
>
> The Atom entry elements are populated as follows :
>
>      * atom:title: not important for processing, can appear in monitoring UI
>      * atom:link: not important for processing, provides a link to the
> event on the source system (this might result in a 404)
>      * atom:id: unique identifier for the event. Important for duplicate
> detection.
>      * atom:updated: the time the event was created at source
>      * atom:summary: not important for processing, can appear in
> monitoring UI, might be useful in describing a system event.
>      * atom:category: the 'term' attribute indicates the event type if
> the "scheme" attribute is 'http://example.org/cat/'. Other schemes are
> not defined.
>
> In addition, two extension elements are inserted into the entry
>
>      * event:EventSource: provides a URI that names the source of the Event.
>      * event:EventLevel:  provides a URI that indcates the
> level/severity of the event.
>
>
> ========
> Event Levels and Types
> ========
>
> Event Levels
> ---------
>
> The level of an event is provided in the event:EventLevel extension
> element. Levels in the element take the form of URIs as follows:
>
> http://example.org/event/{LEVEL}
>
> The defined levels are
>
>      * "trace": for testing
>      * "debug": a debug message
>      * "info": informative; also the default level for a message event
>      * "warn": a warning, typically used in system events
>      * "error": a error, typically used in system events
>      * "critical": a severe event, typically used in system events
>
> Event Types
> -----------
>
> Use of atom:category
>
> The type of an event is provided in the atom:category element. Types use
> the 'scheme' and 'term' attributes. The 'scheme' attribute for a type is
>
> http://example.org/cat/
>
> Categorisation of events
> ------------
>
> An event entry contains 2 such atom:categories.
>
> First, all event entries contain an atom:category stating that they are
> a monitoring event, using a "term" attribute value of 'event' as follows:
>
> <atom:category term="event" scheme="http://example.org/cat/"/>
>
> Second, events are categorised as either system or mesage types, using
> "term" attributes value of 'system' and 'envelope' respectively:
>
>      * System event:
>
> <atom:category term="system" scheme="http://example.org/cat/"/>
>
>      * Message event:
>
> <atom:category term="envelope" scheme="http://example.org/cat/"/>

I've looked at serving Log4J events up as an atom feed, with something
remote to pull it back in. Right now I use the Log4J HtmlAppender to
serve up human only results. I also want to feed out test results of
various unit test runs. There is a patch to do this for Log4J, but it
uses Rome and JDom, which seems a bit of overkill for something that
is just trying to stream out XML I'd rather just generate atom pages
that survive system outage.

right now one inconvenience is that firefox 2 deliberately doesnt
listen to the CSS statements, so I cant format my feed in a way that
is nice for people on FF2.0 and good for machines. annoying.

-steve

On 21 Feb 2007, at 12:23, Edward Summers wrote:
> On Feb 20, 2007, at 5:53 PM, Henry Story wrote:
> > You don't even have to wrap what you publish using atom. See
> > section 5.3
> > http://bitworking.org/projects/atom/draft-ietf-atompub-
> > protocol-13.html#rfc.section.5.3
>
> You mean like when you are posting media resources? [1]
Yes. Your pointer is better than mine.

You could post rdf as a media resource for example, instead of  
wrapping it in the atom content of an entry.

> > And neither does the server have to wrap what he receives in atom.
>
> When posting media resources the app server MUST respond with a link
> to the media link entry which is a URI for an atom:entry. Perhaps I'm
> missing what you mean by 'wrap'?
>
Yes. As the example shows:

[[
     HTTP/1.1 201 Created
     Date: Fri, 7 Oct 2005 17:17:11 GMT
     Content-Length: nnn
     Content-Type: application/atom+xml; charset="utf-8"
     Location: http://example.org/media/edit/the_beach.atom

     <?xml version="1.0"?>
     <entry xmlns="http://www.w3.org/2005/Atom">
       <title>The Beach</title>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2005-10-07T17:17:08Z</updated>
       <author><name>Daffy</name></author>
       <summary type="text" />
       <content type="image/png"
          src="http://media.example.org/the_beach.png"/>
       <link rel="edit-media"
          href="http://media.example.org/edit/the_beach.png" />
       <link rel="edit"
          href="http://example.org/media/edit/the_beach.atom" />
     </entry>
]]

Here the content is at http://media.example.org/the_beach.png

So really the atom server is just creating metadata about  
"...the_beach.png".
That metadata could be expressed in rdf using atom-owl btw:

[] a :Entry;
    :title "The Beach";
    :id "urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"^^xsd:anyUri;
    :updated "2005-10-07T17:17:08Z"^^xsd:dateTime;
    :author [ a foaf:Person;
              :name "Daffy";
            ];
    :summary [ :type "text" ];
    :content [ :type "image/png";
               :src <http://media.example.org/the_beach.png>
              ].

(I left out a few statements)


So it is not xml or rdf formats that are important here. It is that  
we expect the server to do certain things when it receives a POST or  
a PUT. And this is why Atom is a great example of a RESTful web service.

And we could generalise from it. We could define certain well define  
RDF relations which when we PUT or POST them to certain types of  
containers, we expect certain things to be done. For example we might  
want to define Shopping cart containers ( a subclass of :Collection  
perhaps) which when we POST a document that is a BuyOrder does some  
useful things like return us a URL of our Buy Order, which in RDF N3  
would look like this

<> a :BuyOrder;
    :product <http://sun.com/blackbox>
    :amount 25;
    :status "processed";
    :author <http://bblfish.net/people/henry/card#me> .

So if you want you can find an xml crystalisation of the above rdf.  
And then we can do this without requiring people to have rdf tools.  
But since RDF tools are becoming more and more widespread, at some  
point we won't even have to bother about the crystalisation.

see: http://blogs.sun.com/bblfish/entry/250_semantic_web_tools

Hope this shows why I think Atom is both a good example of a RESTful  
service, and why it is not at all incompatible with RDF.

Henry

> //Ed
>
> [1] http://bitworking.org/projects/atom/draft-ietf-atompub-
> protocol-13.html#media-link-entries
>
>

On 2/21/07, Nic James Ferrier <nferrier@...> wrote:
> "Steve Loughran" <steve.loughran.soapbuilders@...> writes:
>
> > right now one inconvenience is that firefox 2 deliberately doesnt
> > listen to the CSS statements, so I cant format my feed in a way that
> > is nice for people on FF2.0 and good for machines. annoying.
>
> Can't you just use XSLT?
>

well, I'm trying to serve up the same feed for people and machines. I
could certainly XSLT it on demand, but I'd rather avoid the effort. It
used to work, that is what annoys me the most.

Hi peeps

This is not the exciting REST application I've been working on (that's
held up as the search for funding goes down the toilet) but it is
still quite interesting - I think.

There are two problems with OpenID as far as I can see:

- the authenticating user is directed away from the website they want
  to login to in order to login.

  I don't think many users will like or understand this. I don't think
  that many webstores (and other sites) will like this.

- having a machine authenticate on your behalf (outside the browser)
  is difficult and requires new protocols to be supported.

prooveme.com attempts to solve both these problems by giving each
OpenID user a client certificate. Now when the user authenticates the
auth happens immediately (the OP can say "does the user have the cert?
yes or no?"). Users won't see any website change as they login (though
they do see a page change obviously).

prooveme.com can also help you get a machine to authenticate on your
behalf. If you give your certificate to a machine then it can use the
existing OpenID protocol to login... as long as the machine's HTTP
client supports HTTPS and redirects. As an example, CURL does.

My idea is to build a small amount of GUI into prooveme.com to allow
users to generate additional certificates with time or login attempt
constraints and to allow those certificates to be distributed to
supporting clients.

If anybody has any thoughts I'd be really interested to hear them.

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

"Steve Loughran" <steve.loughran.soapbuilders@...> writes:

> right now one inconvenience is that firefox 2 deliberately doesnt
> listen to the CSS statements, so I cant format my feed in a way that
> is nice for people on FF2.0 and good for machines. annoying.

Can't you just use XSLT?


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs

"Steve Loughran" <steve.loughran.soapbuilders@...> writes:

> On 2/21/07, Nic James Ferrier <nferrier@...> wrote:
>> "Steve Loughran" <steve.loughran.soapbuilders@...> writes:
>>
>> > right now one inconvenience is that firefox 2 deliberately doesnt
>> > listen to the CSS statements, so I cant format my feed in a way that
>> > is nice for people on FF2.0 and good for machines. annoying.
>>
>> Can't you just use XSLT?
>>
>
> well, I'm trying to serve up the same feed for people and machines. I
> could certainly XSLT it on demand, but I'd rather avoid the effort. It
> used to work, that is what annoys me the most.

I meant embed the XSLT in the feed:

 <?xml version="1.0"?>
 <?xml-stylesheet href="somexslt.xslt" type="application/xml"/>
 <feed ...
 </feed>

your XSLT can render to HTML and that can pull in a CSS.

No?

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk   for all your tapsell ferrier needs